### Expo Framework Setup

Source: https://github.com/heroui-inc/heroui/blob/v3/skills/heroui-native/SKILL.md

Initialize a new Expo project and install the necessary packages for HeroUI Native.

```bash
npx create-expo-app MyApp
cd MyApp
npm i heroui-native uniwind tailwindcss
npm i react-native-reanimated react-native-gesture-handler react-native-safe-area-context @gorhom/bottom-sheet react-native-svg react-native-worklets tailwind-merge tailwind-variants
```

--------------------------------

### Get HeroUI documentation guides

Source: https://github.com/heroui-inc/heroui/blob/v3/skills/heroui-react/SKILL.md

Node script to fetch non-component documentation such as getting-started guides and release notes.

```bash
node scripts/get_docs.mjs /docs/react/getting-started/theming
```

--------------------------------

### HeroUI CLI env command output example

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/react/getting-started/(overview)/cli.mdx

Example output showing installed package versions, status, and system environment info.

```bash
HeroUI CLI <version>

Current installed packages:

╭──────────────────────────────────────────────────────────────────────────────────────╮
│   Package          │   Version          │   Status   │   Docs                        │
│──────────────────────────────────────────────────────────────────────────────────────│
│   @heroui/react    │   3.0.0 🚀latest   │   stable   │   https://heroui.com          │
│   @heroui/styles   │   3.0.0 🚀latest   │   stable   │   https://heroui.com          │
╰──────────────────────────────────────────────────────────────────────────────────────╯

Environment Info:
  System:
    OS: darwin
    CPU: arm64
  Binaries:
    Node: v25.8.1
```

--------------------------------

### Start the development server

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/native/releases/cli-v1-0-0.mdx

Navigate into the project directory and start the Expo development server.

```bash
cd my-app
npm run start
```

--------------------------------

### Common CLI usage examples

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/native/releases/cli-v1-0-0.mdx

Various ways to use the CLI, including interactive mode, specific templates, and skipping installation steps.

```bash
# Fully interactive — prompts for both project name and template
npx create-heroui-native-app@latest

# Project name supplied, template picker still shown
npx create-heroui-native-app@latest my-app

# Fully non-interactive
npx create-heroui-native-app@latest my-app --expo

# Tabs template, install with pnpm
npx create-heroui-native-app@latest my-app --expo-tabs --use-pnpm

# Scaffold only, no install, no git
npx create-heroui-native-app@latest my-app --expo --skip-install --skip-git
```

--------------------------------

### Build HeroUI Components and Start Documentation Server

Source: https://github.com/heroui-inc/heroui/blob/v3/CONTRIBUTING.md

Builds the HeroUI source components and then starts the Next.js development server for documentation.

```bash
## Build HeroUI source components
pnpm build

## Start the next.js documentation dev server
pnpm dev:docs
```

--------------------------------

### HeroUI v2 Code Component Full Example

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/react/migration/(components)/code.mdx

This example demonstrates the usage of the HeroUI v2 `Code` component for displaying installation commands and various styled code snippets.

```tsx
import { Code } from "@heroui/react";

export default function App() {
  return (
    <div className="space-y-4">
      <p>
        Install HeroUI with <Code>npm install @heroui/react</Code>
      </p>
      <div className="flex gap-2">
        <Code color="primary">Primary</Code>
        <Code color="success">Success</Code>
        <Code color="warning">Warning</Code>
        <Code color="danger">Danger</Code>
      </div>
      <div className="flex gap-2 items-center">
        <Code size="sm">Small</Code>
        <Code size="md">Medium</Code>
        <Code size="lg">Large</Code>
      </div>
    </div>
  );
}
```

--------------------------------

### Quick Installation

Source: https://github.com/heroui-inc/heroui/blob/v3/skills/heroui-native/SKILL.md

Install the core library along with all required peer dependencies for React Native.

```bash
npm i heroui-native react-native-reanimated react-native-gesture-handler react-native-safe-area-context @gorhom/bottom-sheet react-native-svg react-native-worklets tailwind-merge tailwind-variants
```

--------------------------------

### Start Storybook Server for Development

Source: https://github.com/heroui-inc/heroui/blob/v3/CONTRIBUTING.md

Starts the Storybook server to facilitate faster component development and testing.

```bash
pnpm sb
```

--------------------------------

### Simple Previous/Next Pagination Controls (v3)

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/react/migration/(components)/pagination.mdx

This example shows a simplified pagination setup with only previous and next buttons, suitable for basic navigation. This pattern was not built-in for v2.

```tsx
const [page, setPage] = useState(1);
const totalPages = 10;

<Pagination>
  <Pagination.Content>
    <Pagination.Item>
      <Pagination.Previous
        isDisabled={page === 1}
        onPress={() => setPage((p) => p - 1)}
      >
        <Pagination.PreviousIcon />
        <span>Previous</span>
      </Pagination.Previous>
    </Pagination.Item>
    <Pagination.Item>
      <Pagination.Next
        isDisabled={page === totalPages}
        onPress={() => setPage((p) => p + 1)}
      >
        <span>Next</span>
        <Pagination.NextIcon />
      </Pagination.Next>
    </Pagination.Item>
  </Pagination.Content>
</Pagination>
```

--------------------------------

### Install MUI Material Packages with npm

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/blog/en/heroui-vs-mui.mdx

This command installs the core MUI Material components along with Emotion for styling. Note that Pigment CSS setup is a separate and experimental process.

```bash
npm install @mui/material @emotion/react @emotion/styled
```

--------------------------------

### Install project dependencies

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/react/getting-started/(overview)/cli.mdx

Navigate to the project directory and install required packages using your preferred manager.

```bash
cd my-heroui-app && npm install
```

```bash
cd my-heroui-app && pnpm install
```

```bash
cd my-heroui-app && yarn install
```

```bash
cd my-heroui-app && bun install
```

--------------------------------

### Install HeroUI Migration Tool via Bash

Source: https://github.com/heroui-inc/heroui/blob/v3/skills/heroui-migration/SKILL.md

Command to download and execute the HeroUI migration script using curl and bash to initialize the migration process.

```bash
curl -fsSL https://heroui.com/install | bash -s heroui-migration
```

--------------------------------

### Install project dependencies

Source: https://github.com/heroui-inc/heroui/blob/v3/CONTRIBUTING.md

Commands to install dependencies in the root folder with hoisting enabled.

```bash
pnpm i --hoist

#or

pnpm install --hoist
```

--------------------------------

### Install HeroUI and HeroUI Pro Packages

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/blog/en/build-react-dashboard-with-heroui.mdx

Installs the necessary HeroUI and HeroUI Pro packages for building a React dashboard.

```bash
npm install @heroui/styles @heroui/react @heroui-pro/react
```

--------------------------------

### Start the development server

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/react/getting-started/(overview)/cli.mdx

Runs the local development server for the newly created project.

```npm
npm run dev
```

--------------------------------

### Basic Accordion Usage with Single Selection

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/native/components/(navigation)/accordion.mdx

This example shows the fundamental setup for an Accordion component, configured to allow only one item to be expanded at a time.

```tsx
<Accordion selectionMode="single">
  <Accordion.Item value="1">
    <Accordion.Trigger>
      ...
      <Accordion.Indicator />
    </Accordion.Trigger>
    <Accordion.Content>...</Accordion.Content>
  </Accordion.Item>
</Accordion>
```

--------------------------------

### Install HeroUI Packages via npm

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/blog/en/why-choose-heroui-for-your-design-system.mdx

Install the core HeroUI styles and React components using npm. This is the first step in setting up HeroUI in your project.

```bash
npm i @heroui/styles @heroui/react
```

--------------------------------

### Install HeroUI v3 Beta 2

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/react/releases/v3-0-0-beta-2.mdx

Use your preferred package manager to install the beta versions of HeroUI styles and React components.

```bash
npm i @heroui/styles@beta @heroui/react@beta
```

```bash
pnpm add @heroui/styles@beta @heroui/react@beta
```

```bash
yarn add @heroui/styles@beta @heroui/react@beta
```

```bash
bun add @heroui/styles@beta @heroui/react@beta
```

--------------------------------

### Full InputOTP Usage Example (React Native)

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/native/components/(forms)/input-otp.mdx

A complete example demonstrating the `InputOTP` component with `Label`, `Description`, and `useRef` for programmatic control like clearing the input after completion.

```tsx
import { InputOTP, Label, Description, type InputOTPRef } from 'heroui-native';
import { View } from 'react-native';
import { useRef } from 'react';

export default function InputOTPExample() {
  const ref = useRef<InputOTPRef>(null);

  const onComplete = (code: string) => {
    console.log('OTP completed:', code);
    setTimeout(() => {
      ref.current?.clear();
    }, 1000);
  };

  return (
    <View className="flex-1 px-5 items-center justify-center">
      <View>
        <Label>Verify account</Label>
        <Description className="mb-3">
          We've sent a code to a****@gmail.com
        </Description>
        <InputOTP ref={ref} maxLength={6} onComplete={onComplete}>
          <InputOTP.Group>
            <InputOTP.Slot index={0} />
            <InputOTP.Slot index={1} />
            <InputOTP.Slot index={2} />
          </InputOTP.Group>
          <InputOTP.Separator />
          <InputOTP.Group>
            <InputOTP.Slot index={3} />
            <InputOTP.Slot index={4} />
            <InputOTP.Slot index={5} />
          </InputOTP.Group>
        </InputOTP>
      </View>
    </View>
  );
}
```

--------------------------------

### Complete Dialog Component Example (TSX)

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/native/components/(overlays)/dialog.mdx

A full, runnable example demonstrating a confirmation dialog with state management, custom content, and multiple action buttons.

```tsx
import { Button, Dialog } from 'heroui-native';
import { View } from 'react-native';
import { useState } from 'react';

export default function DialogExample() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <Dialog isOpen={isOpen} onOpenChange={setIsOpen}>
      <Dialog.Trigger asChild>
        <Button variant="primary">Open Dialog</Button>
      </Dialog.Trigger>
      <Dialog.Portal>
        <Dialog.Overlay />
        <Dialog.Content>
          <Dialog.Close variant="ghost" />
          <View className="mb-5 gap-1.5">
            <Dialog.Title>Confirm Action</Dialog.Title>
            <Dialog.Description>
              Are you sure you want to proceed with this action? This cannot be
              undone.
            </Dialog.Description>
          </View>
          <View className="flex-row justify-end gap-3">
            <Button variant="ghost" size="sm" onPress={() => setIsOpen(false)}>
              Cancel
            </Button>
            <Button size="sm">Confirm</Button>
          </View>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog>
  );
}
```

--------------------------------

### Install next-themes for Next.js

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/react/getting-started/(handbook)/dark-mode.mdx

Install the `next-themes` library using your preferred package manager to enable theme persistence and system preference support in Next.js applications.

```bash
npm i next-themes
```

```bash
pnpm add next-themes
```

```bash
yarn add next-themes
```

```bash
bun add next-themes
```

--------------------------------

### Basic Pagination in HeroUI v3 (Migration Example)

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/react/migration/(components)/pagination.mdx

This example demonstrates how to implement basic pagination in v3 by manually composing `Pagination.Item` and `Pagination.Link` components, managing the active page state with `useState`.

```tsx
import { useState } from "react";
import { Pagination } from "@heroui/react";

const [page, setPage] = useState(1);
const totalPages = 10;

<Pagination>
  <Pagination.Content>
    {Array.from({ length: totalPages }, (_, i) => i + 1).map((p) => (
      <Pagination.Item key={p}>
        <Pagination.Link isActive={page === p} onPress={() => setPage(p)}>
          {p}
        </Pagination.Link>
      </Pagination.Item>
    ))}
  </Pagination.Content>
</Pagination>
```

--------------------------------

### Quick install HeroUI v3 dependencies

Source: https://github.com/heroui-inc/heroui/blob/v3/skills/heroui-react/SKILL.md

npm install command for core HeroUI v3 packages and required dependencies.

```bash
npm i @heroui/styles @heroui/react tailwind-variants
```

--------------------------------

### Full InputGroup Component Example

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/native/components/(forms)/input-group.mdx

A complete, runnable example demonstrating InputGroup with a password input, including state management for visibility toggle.

```tsx
import { InputGroup } from 'heroui-native';
import { Ionicons } from '@expo/vector-icons';
import { useState } from 'react';
import { Pressable, View } from 'react-native';

export default function InputGroupExample() {
  const [value, setValue] = useState('');
  const [isPasswordVisible, setIsPasswordVisible] = useState(false);

  return (
    <View className="px-5">
      <InputGroup>
        <InputGroup.Prefix isDecorative>
          <Ionicons name="lock-closed-outline" size={16} color="#888" />
        </InputGroup.Prefix>
        <InputGroup.Input
          value={value}
          onChangeText={setValue}
          placeholder="Enter your password"
          secureTextEntry={!isPasswordVisible}
        />
        <InputGroup.Suffix>
          <Pressable
            onPress={() => setIsPasswordVisible(!isPasswordVisible)}
            hitSlop={20}
          >
            <Ionicons
              name={isPasswordVisible ? 'eye-off-outline' : 'eye-outline'}
              size={16}
              color="#888"
            />
          </Pressable>
        </InputGroup.Suffix>
      </InputGroup>
    </View>
  );
}
```

--------------------------------

### Install HeroUI Dependencies with Package Managers

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/react/getting-started/(overview)/quick-start.mdx

Install the core HeroUI packages, `@heroui/styles` and `@heroui/react`, using your preferred package manager.

```bash
npm i @heroui/styles @heroui/react
```

```bash
pnpm add @heroui/styles @heroui/react
```

```bash
yarn add @heroui/styles @heroui/react
```

```bash
bun add @heroui/styles @heroui/react
```

--------------------------------

### Install HeroUI Migration Skill with curl

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/react/migration/(migration-for-agents)/agent-skills.mdx

Use this command to install the HeroUI Migration skill directly via a curl script.

```bash
curl -fsSL https://heroui.com/install | bash -s heroui-migration
```

--------------------------------

### Install HeroUI Native Skills with cURL

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/native/getting-started/(ui-for-agents)/agent-skills.mdx

Use this command to install HeroUI Native Skills via a cURL script.

```bash
curl -fsSL https://heroui.com/install | bash -s heroui-native
```

--------------------------------

### Full Description Component Example

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/native/components/(forms)/description.mdx

A complete example demonstrating the integration of `Description` components with multiple form fields for email and password inputs.

```tsx
import { Description, TextField } from 'heroui-native';
import { View } from 'react-native';

export default function DescriptionExample() {
  return (
    <View className="flex-1 justify-center px-5 gap-8">
      <TextField>
        <Label>Email address</Label>
        <Input
          placeholder="Enter your email"
          keyboardType="email-address"
          autoCapitalize="none"
        />
        <Description nativeID="email-desc">
          We'll never share your email with anyone else.
        </Description>
      </TextField>
      <TextField>
        <Label>Password</Label>
        <Input placeholder="Create a password" secureTextEntry />
        <Description nativeID="password-desc">
          Use at least 8 characters with a mix of letters, numbers, and symbols.
        </Description>
      </TextField>
    </View>
  );
}
```

--------------------------------

### Install HeroUI npm packages

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/blog/en/heroui-vs-shadcn.mdx

Use this command to install the core HeroUI styles and React components into your project, enabling traditional package-based usage.

```bash
npm install @heroui/styles @heroui/react
```

--------------------------------

### Complete Card Component Example

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/native/components/(layout)/card.mdx

A comprehensive example demonstrating the `Card` component with nested `Card.Body`, `Card.Title`, `Card.Description`, and `Card.Footer` sections, including `Button` components and `Ionicons`.

```tsx
import { Button, Card } from 'heroui-native';
import { Ionicons } from '@expo/vector-icons';
import { View } from 'react-native';

export default function CardExample() {
  return (
    <Card>
      <View className="gap-4">
        <Card.Body className="mb-4">
          <View className="gap-1 mb-2">
            <Card.Title className="text-pink-500">$450</Card.Title>
            <Card.Title>Living room Sofa • Collection 2025</Card.Title>
          </View>
          <Card.Description>
            This sofa is perfect for modern tropical spaces, baroque inspired
            spaces.
          </Card.Description>
        </Card.Body>
        <Card.Footer className="gap-3">
          <Button variant="primary">Buy now</Button>
          <Button variant="ghost">
            <Button.Label>Add to cart</Button.Label>
            <Ionicons name="bag-outline" size={16} />
          </Button>
        </Card.Footer>
      </View>
    </Card>
  );
}
```

--------------------------------

### Switch with Start and End Content (v2 vs v3)

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/react/migration/(components)/switch.mdx

Demonstrates how to place content at the start and end of the Switch component, highlighting the migration from dedicated props to a structured `Switch.Control` in v3.

```tsx
<Switch
  startContent={<SunIcon />}
  endContent={<MoonIcon />}
>
  Dark mode
</Switch>
```

```tsx
<Switch>
  <Switch.Content>
    <Switch.Control className="flex items-center gap-2">
      <SunIcon />
      <Switch.Thumb />
      <MoonIcon />
    </Switch.Control>
    Dark mode
  </Switch.Content>
</Switch>
```

--------------------------------

### Basic Pagination in HeroUI v2 (Migration Example)

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/react/migration/(components)/pagination.mdx

This example shows the basic usage of the v2 `Pagination` component, which automatically generates page items based on the `total` prop.

```tsx
import { Pagination } from "@heroui/react";

<Pagination total={10} initialPage={1} />
```

--------------------------------

### Full Menu Example with Multiple and Single Selection

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/native/components/(collections)/menu.mdx

A comprehensive example demonstrating a `Menu` with both multiple-selection text styles and single-selection text alignment groups, utilizing `Menu.ItemIndicator` and `variant="dot"`.

```tsx
import type { MenuKey } from 'heroui-native';
import { Button, Menu, Separator } from 'heroui-native';
import { useState } from 'react';
import { Text, View } from 'react-native';

export default function MenuExample() {
  const [textStyles, setTextStyles] = useState<Set<MenuKey>>(
    () => new Set(['bold', 'italic'])
  );
  const [alignment, setAlignment] = useState<Set<MenuKey>>(
    () => new Set(['left'])
  );

  return (
    <Menu>
      <Menu.Trigger asChild>
        <Button variant="secondary">Styles</Button>
      </Menu.Trigger>
      <Menu.Portal>
        <Menu.Overlay />
        <Menu.Content presentation="popover" width={250}>
          <Menu.Label className="mb-1">Text Style</Menu.Label>
          <Menu.Group
            selectionMode="multiple"
            selectedKeys={textStyles}
            onSelectionChange={setTextStyles}
          >
            <Menu.Item id="bold">
              <Menu.ItemIndicator />
              <Menu.ItemTitle>Bold</Menu.ItemTitle>
              <Text className="text-sm text-muted">⌘ B</Text>
            </Menu.Item>
            <Menu.Item id="italic">
              <Menu.ItemIndicator />
              <Menu.ItemTitle>Italic</Menu.ItemTitle>
              <Text className="text-sm text-muted">⌘ I</Text>
            </Menu.Item>
            <Menu.Item id="underline">
              <Menu.ItemIndicator />
              <Menu.ItemTitle>Underline</Menu.ItemTitle>
              <Text className="text-sm text-muted">⌘ U</Text>
            </Menu.Item>
          </Menu.Group>
          <Separator className="mx-2 my-2 opacity-75" />
          <Menu.Label className="mb-1">Text Alignment</Menu.Label>
          <Menu.Group
            selectionMode="single"
            selectedKeys={alignment}
            onSelectionChange={setAlignment}
          >
            <Menu.Item id="left">
              <Menu.ItemIndicator variant="dot" />
              <Menu.ItemTitle>Left</Menu.ItemTitle>
            </Menu.Item>
            <Menu.Item id="center">
              <Menu.ItemIndicator variant="dot" />
              <Menu.ItemTitle>Center</Menu.ItemTitle>
            </Menu.Item>
            <Menu.Item id="right">
              <Menu.ItemIndicator variant="dot" />
              <Menu.ItemTitle>Right</Menu.ItemTitle>
            </Menu.Item>
          </Menu.Group>
        </Menu.Content>
      </Menu.Portal>
    </Menu>
  );
}
```

--------------------------------

### Complete Surface Component Example with Variants (TSX)

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/native/components/(layout)/surface.mdx

This example demonstrates a full implementation of the `Surface` component, showcasing `default`, `secondary`, and `tertiary` variants within a `View` container.

```tsx
import { Surface } from 'heroui-native';
import { Text, View } from 'react-native';

export default function SurfaceExample() {
  return (
    <View className="gap-4">
      <Surface variant="default" className="gap-2">
        <AppText className="text-foreground">Surface Content</AppText>
        <AppText className="text-muted">
          This is a default surface variant. It uses bg-surface styling.
        </AppText>
      </Surface>

      <Surface variant="secondary" className="gap-2">
        <AppText className="text-foreground">Surface Content</AppText>
        <AppText className="text-muted">
          This is a secondary surface variant. It uses bg-surface-secondary
          styling.
        </AppText>
      </Surface>

      <Surface variant="tertiary" className="gap-2">
        <AppText className="text-foreground">Surface Content</AppText>
        <AppText className="text-muted">
          This is a tertiary surface variant. It uses bg-surface-tertiary
          styling.
        </AppText>
      </Surface>
    </View>
  );
}
```

--------------------------------

### Install HeroUI React Package

Source: https://github.com/heroui-inc/heroui/blob/v3/README.md

Use this command to install the main HeroUI React component library package using npm, making it available for use in your project.

```bash
npm install @heroui/react
```

--------------------------------

### Install HeroUI v3 with Next.js App Router

Source: https://github.com/heroui-inc/heroui/blob/v3/skills/heroui-react/SKILL.md

Complete npm install for Next.js App Router setup with HeroUI v3, Tailwind CSS v4, and PostCSS.

```bash
npm i @heroui/styles @heroui/react tailwind-variants tailwindcss @tailwindcss/postcss postcss
```

--------------------------------

### Access Migration Documentation via Node.js Scripts

Source: https://github.com/heroui-inc/heroui/blob/v3/skills/heroui-migration/SKILL.md

A collection of Node.js scripts used to list available migration guides, fetch specific component documentation, or retrieve styling and hooks migration details.

```bash
# List all available component migration guides
node scripts/list_migration_guides.mjs

# Get main migration workflow (full or incremental)
node scripts/get_migration_guide.mjs full
node scripts/get_migration_guide.mjs incremental

# Get component-specific migration guides
node scripts/get_component_migration_guides.mjs button
node scripts/get_component_migration_guides.mjs button card modal

# Get styling migration guide
node scripts/get_styling_migration_guide.mjs

# Get hooks migration guide
node scripts/get_hooks_migration_guide.mjs
```

--------------------------------

### Interactive project initialization output

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/react/getting-started/(overview)/cli.mdx

Example of the interactive prompts and success message when running the init command.

```bash
HeroUI CLI <version>

┌  Create a new project
│
◇  Select a template (Enter to select)
│  ● App (A Next.js 16 with app directory template pre-configured with HeroUI (v3) and Tailwind CSS.)
│  ○ Pages (A Next.js 16 with pages directory template pre-configured with HeroUI (v3) and Tailwind CSS.)
│  ○ Vite (A Vite template pre-configured with HeroUI (v3) and Tailwind CSS.)
│  ○ React Router (A React Router template pre-configured with HeroUI (v3) and Tailwind CSS.)
│
◇  New project name (Enter to skip with default name)
│  my-heroui-app
│
◇  Select a package manager (Enter to select)
│  ● npm
│  ○ yarn
│  ○ pnpm
│  ○ bun
│
◇  Template created successfully!
│
◇  Next steps ───────╮
│                    │
│  cd my-heroui-app  │
│  npm install       │
│                    │
├────────────────────╯
│
└  🚀 Get started with npm run dev
```

--------------------------------

### Start Next.js Documentation Server

Source: https://github.com/heroui-inc/heroui/blob/v3/CONTRIBUTING.md

Launches the Next.js documentation server, which automatically detects changes in components.

```bash
pnpm dev:docs
```

--------------------------------

### Scaffold with specific starter templates

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/native/releases/cli-v1-0-0.mdx

Use flags to specify a template and package manager directly, bypassing interactive prompts.

```bash
npx create-heroui-native-app@latest my-app --expo
npx create-heroui-native-app@latest my-app --expo-tabs --use-pnpm
```

--------------------------------

### Start development server

Source: https://github.com/heroui-inc/heroui/blob/v3/CONTRIBUTING.md

Command to launch the Babel development server for HeroUI core components.

```bash
## Start the dev babel server of HeroUI core components
pnpm dev
```

--------------------------------

### Implementing a Custom Animated Switch with heroui-native

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/native/components/(controls)/switch.mdx

Use this example to create a Switch component with custom animations for background color and thumb position, and animated content for start and end states using `react-native-reanimated` and `Ionicons`.

```tsx
import { Switch } from 'heroui-native';
import { Ionicons } from '@expo/vector-icons';
import React from 'react';
import { View } from 'react-native';
import Animated, { ZoomIn } from 'react-native-reanimated';

export default function SwitchExample() {
  const [darkMode, setDarkMode] = React.useState(false);

  return (
    <View className="flex-row gap-4">
      <Switch
        isSelected={darkMode}
        onSelectedChange={setDarkMode}
        className="w-[56px] h-[32px]"
        animation={{
          backgroundColor: {
            value: ['#172554', '#eab308'],
          },
        }}
      >
        <Switch.Thumb
          className="size-[22px]"
          animation={{
            left: {
              value: 4,
              springConfig: {
                damping: 30,
                stiffness: 300,
                mass: 1,
              },
            },
          }}
        />
        <Switch.StartContent className="left-2">
          {darkMode && (
            <Animated.View key="sun" entering={ZoomIn.springify()}>
              <Ionicons name="sunny" size={16} color="#854d0e" />
            </Animated.View>
          )}
        </Switch.StartContent>
        <Switch.EndContent className="right-2">
          {!darkMode && (
            <Animated.View key="moon" entering={ZoomIn.springify()}>
              <Ionicons name="moon" size={16} color="#dbeafe" />
            </Animated.View>
          )}
        </Switch.EndContent>
      </Switch>
    </View>
  );
}
```

--------------------------------

### Handling DateValue Types with DateField

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/react/components/(date-and-time)/date-field.mdx

This example illustrates how to parse a date string and get today's date using @internationalized/date types, then use these values with the DateField component. It shows how to prepare date values for the value prop.

```tsx
import {parseDate, today, getLocalTimeZone} from '@internationalized/date';

// Parse from string
const date = parseDate('2024-01-15');

// Today's date
const todayDate = today(getLocalTimeZone());

// Use in DateField
<DateField value={date} onChange={setDate}>
  {/* ... */}
</DateField>
```

--------------------------------

### Progressive Disclosure for Button Components

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/react/getting-started/(overview)/design-principles.mdx

Illustrates how HeroUI components support progressive disclosure, allowing you to start with minimal props and add complexity as requirements grow. Examples show a basic button, an enhanced button with an icon, and an advanced button with loading state.

```tsx
// Level 1: Minimal
<Button>Click me</Button>
```

```tsx
// Level 2: Enhanced
<Button variant="primary" size="lg">
  <Icon icon="gravity-ui:check" className="mr-2" />
  Submit
</Button>
```

```tsx
// Level 3: Advanced
<Button variant="primary" isDisabled={isLoading}>
  {isLoading ? <><Spinner size="sm" className="mr-2" /> Loading...</> : 'Submit'}
</Button>
```

--------------------------------

### Initialize a new project

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/react/getting-started/(overview)/cli.mdx

Command syntax for creating a new HeroUI project with optional template and package manager flags.

```bash
heroui init [options]
```

--------------------------------

### Basic Menu Usage

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/native/components/(collections)/menu.mdx

This example demonstrates how to set up a basic floating context menu with a trigger and a few simple menu items.

```tsx
<Menu>
  <Menu.Trigger>...</Menu.Trigger>
  <Menu.Portal>
    <Menu.Overlay />
    <Menu.Content presentation="popover" width={220}>
      <Menu.Item>
        <Menu.ItemTitle>View Profile</Menu.ItemTitle>
      </Menu.Item>
      <Menu.Item>
        <Menu.ItemTitle>Settings</Menu.ItemTitle>
      </Menu.Item>
    </Menu.Content>
  </Menu.Portal>
</Menu>
```

--------------------------------

### Install HeroUI React Skills via curl

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/react/getting-started/(ui-for-agents)/agent-skills.mdx

Use this command to install HeroUI React skills directly from the HeroUI installation script.

```bash
curl -fsSL https://heroui.com/install | bash -s heroui-react
```

--------------------------------

### List installed HeroUI packages

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/react/getting-started/(overview)/cli.mdx

Displays the currently installed versions and status of HeroUI packages.

```bash
heroui list [options]
```

```text
HeroUI CLI <version>

Current installed packages:

╭──────────────────────────────────────────────────────────────────────────────────────╮
│   Package          │   Version          │   Status   │   Docs                        │
│──────────────────────────────────────────────────────────────────────────────────────│
│   @heroui/react    │   3.0.0 🚀latest   │   stable   │   https://heroui.com          │
│   @heroui/styles   │   3.0.0 🚀latest   │   stable   │   https://heroui.com          │
╰──────────────────────────────────────────────────────────────────────────────────────╯
```

--------------------------------

### Documentation and Theme Scripts

Source: https://github.com/heroui-inc/heroui/blob/v3/skills/heroui-native/SKILL.md

Use these scripts to list components, fetch MDX documentation, or retrieve theme variables.

```bash
node scripts/list_components.mjs
```

```bash
node scripts/get_component_docs.mjs Button
```

```bash
node scripts/get_component_docs.mjs Button Card TextField
```

```bash
node scripts/get_theme.mjs
```

```bash
node scripts/get_docs.mjs /docs/native/getting-started/theming
```

--------------------------------

### Install HeroUI CLI globally

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/react/getting-started/(overview)/cli.mdx

Installs the CLI tool globally on your system using npm.

```npm
npm install heroui-cli@latest -g
```

--------------------------------

### Initialize and Add shadcn/ui Components

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/blog/en/heroui-vs-shadcn.mdx

Initializes shadcn/ui in your project and adds specific components individually. The CLI handles dependency resolution.

```bash
npx shadcn@latest init
npx shadcn@latest add button card table dialog
```

--------------------------------

### Display HeroUI CLI help

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/react/getting-started/(overview)/cli.mdx

Shows all available commands and global options for the CLI.

```bash
heroui
```

--------------------------------

### Conventional commit message example

Source: https://github.com/heroui-inc/heroui/blob/v3/CONTRIBUTING.md

An example of a commit message following the category(scope): message convention.

```text
feat(components): add new prop to the avatar component
```

--------------------------------

### Using Simple Components like Button

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/react/getting-started/(handbook)/composition.mdx

Demonstrates various ways to use simple components like Button, including direct usage, with '.Root' suffix, and via named exports.

```tsx
import { Button } from '@heroui/react';

// Recommended - no .Root needed
<Button>Click me</Button>

// Or with .Root
<Button.Root>Click me</Button.Root>

// Or named export
import { ButtonRoot } from '@heroui/react';
<ButtonRoot>Click me</ButtonRoot>
```

--------------------------------

### Get HeroUI component documentation

Source: https://github.com/heroui-inc/heroui/blob/v3/skills/heroui-react/SKILL.md

Node script to fetch MDX documentation for one or multiple components.

```bash
node scripts/get_component_docs.mjs Button
node scripts/get_component_docs.mjs Button Card TextField
```

--------------------------------

### Create Next.js Project with HeroUI CLI

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/react/getting-started/(overview)/frameworks.mdx

Use the HeroUI CLI to initialize a new Next.js project. Select either the App or Pages template when prompted.

```bash
npx heroui-cli@latest init
```

--------------------------------

### Complete TextArea Example

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/native/components/(forms)/text-area.mdx

A full React Native component example demonstrating multiple TextArea variants within a layout.

```tsx
import { Description, FieldError, Label, TextArea, TextField } from 'heroui-native';
import { View } from 'react-native';

export default function TextAreaExample() {
  return (
    <View className="gap-8">
      <TextField>
        <Label>Primary Variant</Label>
        <TextArea placeholder="Primary style text area" variant="primary" />
        <Description>Default variant with primary styling</Description>
      </TextField>

      <TextField>
        <Label>Secondary Variant</Label>
        <TextArea
          placeholder="Secondary style text area"
          variant="secondary"
        />
        <Description>Secondary variant for surfaces</Description>
      </TextField>
    </View>
  );
}
```

--------------------------------

### Chip Component Usage Examples

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/native/components/(data-display)/chip.mdx

Examples showing different sizes, variants, and custom compositions using icons and the Chip.Label sub-component.

```tsx
import { Chip } from 'heroui-native';
import { View, Text } from 'react-native';
import { Ionicons } from '@expo/vector-icons';

export default function ChipExample() {
  return (
    <View className="gap-4 p-4">
      <View className="flex-row flex-wrap gap-2">
        <Chip size="sm">Small</Chip>
        <Chip size="md">Medium</Chip>
        <Chip size="lg">Large</Chip>
      </View>

      <View className="flex-row flex-wrap gap-2">
        <Chip variant="primary" color="accent">
          Primary
        </Chip>
        <Chip variant="secondary" color="success">
          <View className="size-1.5 rounded-full bg-success" />
          <Chip.Label>Success</Chip.Label>
        </Chip>
        <Chip variant="tertiary" color="warning">
          <Ionicons name="star" size={12} color="#F59E0B" />
          <Chip.Label>Premium</Chip.Label>
        </Chip>
      </View>

      <View className="flex-row gap-2">
        <Chip variant="secondary">
          <Chip.Label>Remove</Chip.Label>
          <Ionicons name="close" size={14} color="#6B7280" />
        </Chip>
        <Chip className="bg-purple-600">
          <Chip.Label className="text-white font-semibold">Custom</Chip.Label>
        </Chip>
      </View>
    </View>
  );
}
```

--------------------------------

### Kbd v2 Default Variant Example

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/react/migration/(components)/kbd.mdx

Example of Kbd component usage in HeroUI v2, showing a basic key combination.

```tsx
<Kbd keys={["command"]}>K</Kbd>
```

--------------------------------

### v2 Form Validation Examples

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/react/migration/(components)/input.mdx

Examples of form validation and description handling using the single `Input` component in HeroUI v2.

```tsx
{/* With description */}
<Input
  description="We'll never share your email"
  label="Email"
  type="email"
/>

{/* With error message */}
<Input
  errorMessage="Please enter a valid email"
  isInvalid
  label="Email"
  type="email"
/>

{/* Required */}
<Input isRequired label="Email" type="email" />
```

--------------------------------

### List all available HeroUI components

Source: https://github.com/heroui-inc/heroui/blob/v3/skills/heroui-react/SKILL.md

Node script to display all available components in the HeroUI library.

```bash
node scripts/list_components.mjs
```

--------------------------------

### Full Separator Component Example

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/native/components/(layout)/separator.mdx

A complete example demonstrating the Separator component with various configurations within a React Native view.

```tsx
import { Separator, Surface } from 'heroui-native';
import { Text, View } from 'react-native';

export default function SeparatorExample() {
  return (
    <Surface variant="secondary" className="px-6 py-7">
      <Text className="text-base font-medium text-foreground">
        HeroUI Native
      </Text>
      <Text className="text-sm text-muted">
        A modern React Native component library.
      </Text>
      <Separator className="my-4" />
      <View className="flex-row items-center h-5">
        <Text className="text-sm text-foreground">Components</Text>
        <Separator orientation="vertical" className="mx-3" />
        <Text className="text-sm text-foreground">Themes</Text>
        <Separator orientation="vertical" className="mx-3" />
        <Text className="text-sm text-foreground">Examples</Text>
      </View>
    </Surface>
  );
}
```

--------------------------------

### Install HeroUI React and Styles

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/react/releases/v3-2-1.mdx

Update your project to the latest versions of `@heroui/styles` and `@heroui/react` using your preferred package manager.

```bash
npm i @heroui/styles@latest @heroui/react@latest
```

```bash
pnpm add @heroui/styles@latest @heroui/react@latest
```

```bash
yarn add @heroui/styles@latest @heroui/react@latest
```

```bash
bun add @heroui/styles@latest @heroui/react@latest
```

--------------------------------

### Build Project Package

Source: https://github.com/heroui-inc/heroui/blob/v3/CONTRIBUTING.md

Builds the entire project package using either pnpm or npm.

```bash
# Build current code

pnpm build
```

```bash
# or

npm run build
```

--------------------------------

### Git Commit Examples

Source: https://github.com/heroui-inc/heroui/blob/v3/CLAUDE.md

Illustrative examples of valid Git commit messages following the conventional commit format for various types of changes.

```bash
git commit -m "feat(components): add new prop to avatar component"
git commit -m "fix(button): resolve click handler issue"
git commit -m "docs: update installation guide"
git commit -m "ci: add Claude Code GitHub Action workflow"
```

--------------------------------

### Install HeroUI v3 Packages with pnpm Aliases

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/react/migration/(workflows)/incremental-migration.mdx

Installs HeroUI v3 packages with pnpm aliases, enabling them to coexist with v2 dependencies in the same project.

```json
{
  "dependencies": {
    "@heroui/react": "2.8.6",
    "@heroui/theme": "2.4.24",
    "@heroui-v3/react": "npm:@heroui/react@latest",
    "@heroui-v3/styles": "npm:@heroui/styles@latest"
  }
}
```

--------------------------------

### Download HeroUI v2 to v3 Migration Docs

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/react/migration/(migration-for-agents)/agents-md.mdx

Use this command to download HeroUI v2 to v3 migration documentation into your project's `.heroui-docs/migration/` directory.

```bash
npx heroui-cli@latest agents-md --migration
```

--------------------------------

### Basic and Sectioned Menu Usage

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/native/releases/rc-3.mdx

This example demonstrates how to implement a basic menu with individual items and a more advanced menu featuring sections, labels, and single selection mode using `Menu.Group` and `Menu.ItemIndicator`.

```tsx
import { Menu } from "heroui-native";

export function BasicMenu() {
  return (
    <Menu>
      <Menu.Trigger>
        <Button>Open Menu</Button>
      </Menu.Trigger>
      <Menu.Portal>
        <Menu.Overlay />
        <Menu.Content>
          <Menu.Item>
            <Menu.ItemTitle>Edit</Menu.ItemTitle>
          </Menu.Item>
          <Menu.Item>
            <Menu.ItemTitle>Duplicate</Menu.ItemTitle>
          </Menu.Item>
          <Menu.Item variant="danger">
            <Menu.ItemTitle>Delete</Menu.ItemTitle>
          </Menu.Item>
        </Menu.Content>
      </Menu.Portal>
    </Menu>
  );
}

export function MenuWithSections() {
  return (
    <Menu>
      <Menu.Trigger>
        <Button>Actions</Button>
      </Menu.Trigger>
      <Menu.Portal>
        <Menu.Overlay />
        <Menu.Content>
          <Menu.Group selectionMode="single" selectedKeys={selected} onSelectionChange={setSelected}>
            <Menu.Label>View</Menu.Label>
            <Menu.Item id="list">
              <Menu.ItemTitle>List View</Menu.ItemTitle>
              <Menu.ItemIndicator />
            </Menu.Item>
            <Menu.Item id="grid">
              <Menu.ItemTitle>Grid View</Menu.ItemTitle>
              <Menu.ItemIndicator />
            </Menu.Item>
          </Menu.Group>
        </Menu.Content>
      </Menu.Portal>
    </Menu>
  );
}
```

--------------------------------

### v3 Form Validation Examples

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/react/migration/(components)/input.mdx

Examples demonstrating form validation, description, and required fields using the `TextField` component and its sub-components in HeroUI v3.

```tsx
import { Description } from "@heroui/react";

{/* With description */}
<TextField name="email" type="email">
  <Label>Email</Label>
  <Input />
  <Description>We'll never share your email</Description>
  <FieldError />
</TextField>

{/* With error message */}
<TextField
  isInvalid
  name="email"
  type="email"
  validate={(value) => {
    if (!/^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$/i.test(value)) {
      return "Please enter a valid email";
    }
    return null;
  }}
>
  <Label>Email</Label>
  <Input />
  <FieldError />
</TextField>

{/* Required */}
<TextField isRequired name="email" type="email">
  <Label>Email</Label>
  <Input />
  <FieldError />
</TextField>
```

--------------------------------

### Full LinkButton Example with Checkbox (TSX)

Source: https://github.com/heroui-inc/heroui/blob/v3/apps/docs/content/docs/en/native/components/(buttons)/link-button.mdx

A complete example demonstrating LinkButton integration with a checkbox and a regular button, managing state for user agreement.

```tsx
import { Button, Checkbox, ControlField, LinkButton } from 'heroui-native';
import React from 'react';
import { Alert, View } from 'react-native';

export default function LinkButtonExample() {
  const [isAgreed, setIsAgreed] = React.useState(false);

  const handleTermsPress = () => Alert.alert('Terms', 'Navigate to Terms');
  const handlePrivacyPress = () =>
    Alert.alert('Privacy', 'Navigate to Privacy Policy');

  return (
    <View className="flex-1 px-5 items-center justify-center">
      <View className="w-full max-w-xs gap-6">
        <ControlField
          isSelected={isAgreed}
          onSelectedChange={setIsAgreed}
          className="items-start"
        >
          <ControlField.Indicator>
            <Checkbox className="mt-0.5" />
          </ControlField.Indicator>
          <View className="flex-row flex-wrap flex-1">
            <Text className="text-sm text-muted">I agree to the </Text>
            <LinkButton size="sm" onPress={handleTermsPress}>
              <LinkButton.Label className="text-accent">
                Terms of Service
              </LinkButton.Label>
            </LinkButton>
            <Text className="text-sm text-muted"> and </Text>
            <LinkButton size="sm" onPress={handlePrivacyPress}>
              <LinkButton.Label className="text-accent">
                Privacy Policy
              </LinkButton.Label>
            </LinkButton>
          </View>
        </ControlField>
        <Button isDisabled={!isAgreed}>Sign up</Button>
      </View>
    </View>
  );
}
```