Webf Native Ui

Platforms: iOS, macOS (optimized for iOS design)

Component Count: 30+ components

Available Components:

• Navigation & Layout: Tab, Scaffold, TabBar, TabView
• Dialogs & Sheets: Alert Dialog, Action Sheet, Modal Popup, Context Menu
• Lists: List Section, List Tile
• Forms: Form Section, Form Row, TextField, Search Field
• Pickers: Date Picker, Time Picker
• Controls: Button, Switch, Slider, Segmented Control, Checkbox, Radio
• Icons: 1000+ SF Symbols
• Colors: Cupertino color system

NPM Packages:

• React: @openwebf/react-cupertino-ui
• Vue: @openwebf/vue-cupertino-ui

Flutter Package: webf_cupertino_ui

Documentation: https://openwebf.com/en/ui-components/cupertino

When to Use Native UI vs HTML/CSS

Use Cupertino UI When:

• ✅ Building iOS-style apps
• ✅ Need native-looking iOS forms, buttons, and controls
• ✅ Want 60fps native performance for complex UIs
• ✅ Building iOS lists, dialogs, or navigation patterns
• ✅ Need Apple's Human Interface Guidelines design language

Use HTML/CSS When:

• ✅ Building custom designs that don't follow platform patterns
• ✅ Using existing web component libraries (e.g., Tailwind CSS)
• ✅ Need maximum flexibility in styling
• ✅ Porting existing web apps
• ✅ Building cross-platform designs (not platform-specific)

Setup Instructions

Step 1: Configure Flutter Project (Optional)

If you have access to the Flutter project hosting your WebF app:

For Cupertino UI:

1. Open your Flutter project's pubspec.yaml
2. Add the dependency:

   dependencies:
     webf_cupertino_ui: ^1.0.0
   

3. Run: flutter pub get
4. Initialize in your main Dart file:

   import 'package:webf/webf.dart';
   import 'package:webf_cupertino_ui/webf_cupertino_ui.dart';
   
   void main() {
     WebFControllerManager.instance.initialize(WebFControllerManagerConfig(
       maxAliveInstances: 2,
       maxAttachedInstances: 1,
     ));
   
     // Install Cupertino UI components
     installWebFCupertinoUI();
   
     runApp(MyApp());
   }
   

Step 2: Install NPM Packages (JavaScript/TypeScript)

For React:

npm install @openwebf/react-cupertino-ui

For Vue:

npm install @openwebf/vue-cupertino-ui

Step 3: Using Components in Your Code

React Example:

import { FlutterCupertinoButton, FlutterCupertinoTextField } from '@openwebf/react-cupertino-ui';

export function MyComponent() {
  return (
    <div>
      <FlutterCupertinoTextField
        placeholder="Enter your name"
        onChanged={(value) => console.log('Value:', value)}
      />
      <FlutterCupertinoButton
        variant="filled"
        onClick={() => console.log('Clicked')}
      >
        Submit
      </FlutterCupertinoButton>
    </div>
  );
}

Vue Example:

<template>
  <div>
    <FlutterCupertinoTextField
      placeholder="Enter your name"
      @changed="handleChange"
    />
    <FlutterCupertinoButton
      variant="filled"
      @click="handleClick"
    >
      Submit
    </FlutterCupertinoButton>
  </div>
</template>

<script setup>
import { FlutterCupertinoTextField, FlutterCupertinoButton } from '@openwebf/vue-cupertino-ui';

const handleChange = (value) => {
  console.log('Value:', value);
};

const handleClick = () => {
  console.log('Clicked');
};
</script>

Component Reference

See the Native UI Component Reference for a complete list of available components and their properties.

Common Patterns

1. Building an iOS-Style Form

import {
  FlutterCupertinoFormSection,
  FlutterCupertinoFormRow,
  FlutterCupertinoTextField,
  FlutterCupertinoButton
} from '@openwebf/react-cupertino-ui';

export function ProfileForm() {
  return (
    <FlutterCupertinoFormSection header="Profile Information">
      <FlutterCupertinoFormRow label="Name">
        <FlutterCupertinoTextField placeholder="John Doe" />
      </FlutterCupertinoFormRow>
      <FlutterCupertinoFormRow label="Email">
        <FlutterCupertinoTextField
          placeholder="[email protected]"
          keyboardType="email"
        />
      </FlutterCupertinoFormRow>
      <FlutterCupertinoButton variant="filled">
        Save Changes
      </FlutterCupertinoButton>
    </FlutterCupertinoFormSection>
  );
}

2. Building a Settings Screen

import {
  FlutterCupertinoListSection,
  FlutterCupertinoListTile,
  FlutterCupertinoSwitch
} from '@openwebf/react-cupertino-ui';

export function SettingsScreen() {
  return (
    <FlutterCupertinoListSection header="Settings">
      <FlutterCupertinoListTile
        title="Notifications"
        trailing={<FlutterCupertinoSwitch value={true} />}
      />
      <FlutterCupertinoListTile
        title="Dark Mode"
        trailing={<FlutterCupertinoSwitch value={false} />}
      />
    </FlutterCupertinoListSection>
  );
}

3. Showing a Native Dialog

import { FlutterCupertinoAlertDialog } from '@openwebf/react-cupertino-ui';

export function ConfirmationDialog({ onConfirm, onCancel }) {
  return (
    <FlutterCupertinoAlertDialog
      title="Confirm Action"
      content="Are you sure you want to proceed?"
      actions={[
        { label: 'Cancel', onPress: onCancel },
        { label: 'Confirm', onPress: onConfirm, isDestructive: true }
      ]}
    />
  );
}

Best Practices

1. Mix Native UI with HTML/CSS

You don't have to use native UI everywhere. Mix and match:

// Use native components for platform-specific UIs
<FlutterCupertinoButton variant="filled">
  Save
</FlutterCupertinoButton>

// Use HTML/CSS for custom layouts
<div className="custom-layout">
  <h1>Custom Design</h1>
  <p>This uses regular HTML/CSS</p>
</div>

2. Use Native UI for Complex Components

Native UI components handle complex interactions better:

• Date pickers → Use FlutterCupertinoDatePicker instead of HTML input
• Sliders → Use FlutterCupertinoSlider for native feel
• Segmented controls → Use FlutterCupertinoSegmentedControl

3. Check Component Documentation

Always check the official documentation for component props and events:

• https://openwebf.com/en/ui-components/cupertino

4. Use TypeScript for Type Safety

All native UI packages include TypeScript definitions:

import type { FlutterCupertinoButtonProps } from '@openwebf/react-cupertino-ui';

const buttonProps: FlutterCupertinoButtonProps = {
  variant: 'filled',
  onClick: () => console.log('Clicked')
};

Troubleshooting

Issue: Components Not Rendering

Cause: Flutter package not installed or initialized

Solution:

1. Check that the Flutter package is in pubspec.yaml
2. Verify installWebFCupertinoUI() is called in main.dart
3. Run flutter pub get
4. Rebuild your Flutter app

Issue: TypeScript Errors for Components

Cause: NPM package not installed correctly

Solution:

# Reinstall the package
npm install @openwebf/react-cupertino-ui --save

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

Issue: Vue Components Not Found

Cause: Vue bindings need to be generated

Solution: Follow the "For Vue + Cupertino UI" steps in Step 2 above to generate Vue bindings using webf codegen.

Issue: Props Don't Match Flutter Widget

Cause: WebF automatically converts between JavaScript and Dart naming

Solution:

• JavaScript uses camelCase: onClick, onChange, placeholder
• Flutter uses camelCase too, so props map directly
• Check documentation for exact prop names

Resources

• Component Gallery: https://openwebf.com/en/ui-components
• Cupertino UI Docs: https://openwebf.com/en/ui-components/cupertino
• WebF CLI Docs: https://openwebf.com/en/docs/tools/webf-cli
• React Examples: https://github.com/openwebf/react-cupertino-gallery
• Vue Examples: https://github.com/openwebf/vue-cupertino-gallery

Next Steps

After setting up native UI:

1. Explore components: Visit https://openwebf.com/en/ui-components to see all available components
2. Check examples: Look at the gallery apps for React and Vue
3. Mix with HTML/CSS: Use native UI where it makes sense, HTML/CSS elsewhere
4. Performance: Native UI components render at 60fps with Flutter-level performance

Summary

• ✅ Native UI libraries provide pre-built, platform-specific components
• ✅ Cupertino UI for iOS-style apps (30+ components available now)
• ✅ Form UI for validated forms (available now)
• ✅ Material UI coming soon for Android-style apps
• ✅ Install Flutter packages first, then npm packages
• ✅ Mix native UI with HTML/CSS as needed
• ✅ Better performance than HTML/CSS for complex UIs
• ✅ Full React and Vue support