/webf-native-ui

name: webf-native-ui
description: Setup and use WebF's Cupertino UI library to build native iOS-style UIs with pre-built components instead of crafting everything with HTML/CSS. Use when building iOS apps, adding native UI components, or improving UI performance.

WebF Native UI Libraries

Instead of crafting all UIs with HTML/CSS, WebF provides **pre-built native UI libraries** that render as native Flutter widgets with full native performance. These components look and feel native on each platform while being controlled from your JavaScript code.

What Are Native UI Libraries?

Native UI libraries are collections of UI components that:

• **Render as native Flutter widgets** (not DOM elements)
• **Look and feel native** on each platform (iOS, Android, etc.)
• **Provide better performance** than HTML/CSS for complex UIs
• **Use platform-specific design** (Cupertino for iOS, Material for Android)
• **Work with React, Vue, and vanilla JavaScript**

Available Library

Cupertino UI ✅

**Description**: iOS-style components following Apple's Human Interface Guidelines

**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](./reference.md) 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="john@example.com"
          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>
  );
}
`