` element) * Should be associated with form field via ARIA * Error styling provides visual feedback * Works with screen readers ## Styling The component uses the class name `GeckoUIInputError`. Override styles using the `className` prop: ```css .GeckoUIInputError { /* Default error styling */ } ``` ## Related Components * [Label](/docs/label) - Form field labels * [Input](/docs/input) - Text input fields * [Alert](/docs/alert) - Page-level messages * [RHFInput](/docs/rhf-input) - React Hook Form input integration # Input import { Input } from '@geckoui/geckoui'; import { SearchIcon, MailIcon } from 'lucide-react'; # Input A versatile text input component that supports prefix and suffix elements like icons or text labels. The component automatically adjusts element widths based on content. ## Installation ```tsx import { Input } from '@geckoui/geckoui'; ``` ## Basic Usage ```tsx ``` ## Props API | Prop | Type | Default | Description | | ---------------- | ------------------------------------- | ------- | --------------------------------------------------------------------- | | `prefix` | `ReactNode \| ((props) => ReactNode)` | - | Element displayed before the input (icon, text, or component) | | `suffix` | `ReactNode \| ((props) => ReactNode)` | - | Element displayed after the input (icon, text, or component) | | `inputClassName` | `string` | - | CSS class for the input element itself (for placeholder styles, etc.) | | `className` | `string` | - | CSS class for the container wrapping prefix, input, and suffix | | `disabled` | `boolean` | `false` | Disable the input | | `readOnly` | `boolean` | `false` | Make the input read-only | | ...rest | `InputHTMLAttributes` | - | All standard HTML input attributes | ## Examples ### With Prefix Icon } placeholder="Search..." /> ```tsx import { SearchIcon } from 'lucide-react'; } placeholder="Search..." /> ``` ### With Suffix Text ```tsx ``` ### With Both Prefix and Suffix ```tsx ``` ### Email Input } placeholder="your.email@example.com" /> ```tsx import { MailIcon } from 'lucide-react'; } placeholder="your.email@example.com" /> ``` ### URL Input ```tsx ``` ### Disabled State ```tsx ``` ### Read-Only State ```tsx ``` ## Accessibility * Input is wrapped in a `` for better accessibility * Automatically generates unique IDs if not provided * Supports `aria-disabled` attribute * Fully keyboard navigable * Works with screen readers ## Styling The component uses BEM-style class names: * `GeckoUIInput` - Main container * `GeckoUIInput--enabled` - Applied when not disabled * `GeckoUIInput--disabled` - Applied when disabled * `GeckoUIInput--readonly` - Applied when read-only * `GeckoUIInput__input` - The actual input element Override styles using `className` for the container or `inputClassName` for the input element. ## Related Components * [Textarea](/docs/textarea) - Multi-line text input * [Label](/docs/label) - Form labels with tooltip support * [InputError](/docs/input-error) - Error message display * [RHFInput](/docs/rhf-input) - React Hook Form integration # Installation # Installation This guide will help you install and configure Gecko UI in your project. ## Prerequisites Before installing Gecko UI, ensure you have: * **Node.js** 18.0.0 or higher * **React** 19.2.0 or higher * **React DOM** 19.2.0 or higher ## Package Installation Install Gecko UI using your preferred package manager: ```bash npm install @geckoui/geckoui ``` ```bash pnpm add @geckoui/geckoui ``` ```bash yarn add @geckoui/geckoui ``` Install `react-hook-form`, which is required for form components: ```bash npm install react-hook-form ``` ```bash pnpm add react-hook-form ``` ```bash yarn add react-hook-form ``` ## Style Setup ### 1. Import Base Styles Import the main stylesheet in your root layout or main entry file: ```tsx title="app/layout.tsx" import '@geckoui/geckoui/styles.css'; export default function RootLayout({ children }) { return ( {children} ); } ``` ```tsx title="src/main.tsx" import '@geckoui/geckoui/styles.css'; import React from 'react'; import ReactDOM from 'react-dom/client'; import App from './App'; ReactDOM.createRoot(document.getElementById('root')!).render( ); ``` ### 2. Import styles for tailwindcss If you use `tailwindcss`, make sure to import the css inside `layer` directive to correctly override the styles: ```css title="src/global.css" @import "tailwindcss"; @layer components { @import "@geckoui/geckoui/styles.css"; /* Optional if you use Markdown component */ @import "@geckoui/geckoui/markdown.css"; } ``` ### 3. Import Markdown Styles (Optional) If you're using the Markdown component, also import its stylesheet: ```tsx import '@geckoui/geckoui/markdown.css'; ``` ## Container Setup Add `GeckoUIPortal` to your layout. This is **required** for the following components: * Dialog * Drawer * ConfirmDialog * Toast ```tsx title="app/layout.tsx" import { GeckoUIPortal } from '@geckoui/geckoui'; import '@geckoui/geckoui/styles.css'; export default function RootLayout({ children }) { return ( {children} ); } ``` ```tsx title="src/App.tsx" import { GeckoUIPortal } from '@geckoui/geckoui'; function App() { return (

{/* Your app content */}

); } export default App; ``` # Label import { Label, Input, Textarea } from '@geckoui/geckoui'; # Label A label component for input fields with support for required indicators and tooltips. When `required` is true, displays a red asterisk (\*) after the label text. When `tooltip` is provided, displays a tooltip icon with helpful information. ## Installation ```tsx import { Label } from '@geckoui/geckoui'; ``` ## Basic Usage Username ```tsx Username ``` ## Props API | Prop | Type | Default | Description | | ------------------------ | --------------------- | ------- | ---------------------------------- | | `htmlFor` | `string` | - | ID of the associated input element | | `required` | `boolean` | `false` | Show red asterisk indicator | | `tooltip` | `string` | - | Tooltip text to display | | `tooltipIcon` | `ReactNode \| FC` | - | Custom tooltip icon | | `tooltipBackgroundColor` | `string` | - | Tooltip background color | | `tooltipClassName` | `string` | - | CSS class for tooltip | | `className` | `string` | - | CSS class for label | | ...rest | `LabelHTMLAttributes` | - | All standard label attributes | ## Examples ### Required Field

Email Address

```tsx Email Address ``` ### With Tooltip

Password

```tsx Password ``` ### Required with Tooltip

API Key

```tsx API Key ``` ### Custom Tooltip Styling

Display Name

```tsx Display Name ``` ### Form with Multiple Labels

Username

Bio

</div>
  </div>
</Preview>

```tsx
<div className="space-y-1">
  <Label htmlFor="username" required>Username</Label>
  <Input id="username" />
</div>

<div className="space-y-1">
  <Label htmlFor="email" required>Email</Label>
  <Input id="email" type="email" />
</div>

<div className="space-y-1">
  <Label htmlFor="bio" tooltip="Tell us about yourself">Bio</Label>
  <Textarea id="bio" />
</div>
```

### Custom Styling

<Preview>
  <div className="space-y-4">
    <Label htmlFor="field1" className="text-lg font-bold text-blue-600">
      Large Bold Label
    </Label>

<Label htmlFor="field2" className="text-sm text-gray-500">
      Small Gray Label
    </Label>
  </div>
</Preview>

```tsx
<Label htmlFor="field1" className="text-lg font-bold text-blue-600">
  Large Bold Label
</Label>

<Label htmlFor="field2" className="text-sm text-gray-500">
  Small Gray Label
</Label>
```

## Features

### Required Indicator

When `required={true}`, a red asterisk (\*) is appended to the label text:

```tsx
<Label required>Email Address</Label>
// Displays: Email Address *
```

**Note**: This is just a visual indicator and does not enforce validation. You must still add validation logic to your form.

### Tooltip

When `tooltip` prop is provided, an icon appears next to the label. Hovering over it shows the tooltip:

```tsx
<Label tooltip="Additional help text">
  Field Name
</Label>
```

You can customize the tooltip with:

* `tooltipBackgroundColor` - Change background color
* `tooltipClassName` - Add custom CSS classes
* `tooltipIcon` - Use a custom icon instead of default

## Accessibility

* Uses semantic `<label>` element
* Associates with input via `htmlFor` attribute
* Tooltip has proper ARIA attributes
* Required indicator is visible
* Works with screen readers
* Keyboard accessible tooltip

## Styling

The component uses BEM-style class names:

* `GeckoUILabel` - Main label element
* `GeckoUILabel__required-indicator` - Red asterisk
* `GeckoUILabel__tooltip` - Tooltip wrapper
* `GeckoUILabel__tooltip-icon` - Default tooltip icon

## Dependencies

This component uses the internal `Tooltip` component for tooltip functionality.

## Related Components

* [Input](/docs/input) - Text input fields
* [Textarea](/docs/textarea) - Multi-line text input
* [Tooltip](/docs/tooltip) - Standalone tooltips
* [InputError](/docs/input-error) - Error messages

# LoadingButton

import { LoadingButton } from '@geckoui/geckoui';
import { AsyncOperationExample } from '@/components/examples/loading-button-examples';

# LoadingButton

LoadingButton extends the Button component with built-in loading state visualization. Automatically displays a spinner and optional loading text while preventing user interaction during asynchronous operations.

## Installation

```tsx
import { LoadingButton } from '@geckoui/geckoui';
```

## Basic Usage

<Preview>
  <LoadingButton loading>
    Loading...
  </LoadingButton>
</Preview>

```tsx
import { useState } from 'react';

function Example() {
  const [loading, setLoading] = useState(false);

const handleClick = async () => {
    setLoading(true);
    await someAsyncOperation();
    setLoading(false);
  };

return (
    <LoadingButton loading={loading} onClick={handleClick}>
      Submit
    </LoadingButton>
  );
}
```

## Props API

| Prop              | Type                                          | Default     | Description                                   |
| ----------------- | --------------------------------------------- | ----------- | --------------------------------------------- |
| `loading`         | `boolean`                                     | `false`     | Display loading state with spinner            |
| `loadingText`     | `string`                                      | -           | Text to show when loading (replaces children) |
| `spinnerPosition` | `'start' \| 'end'`                            | `'start'`   | Position of the spinner                       |
| `variant`         | `'filled' \| 'outlined' \| 'ghost' \| 'icon'` | `'filled'`  | Button visual style                           |
| `size`            | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`        | `'md'`      | Button size                                   |
| `color`           | `'primary'`                                   | `'primary'` | Button color scheme                           |
| `disabled`        | `boolean`                                     | `false`     | Disable the button                            |
| ...rest           | `ButtonHTMLAttributes`                        | -           | All standard Button props                     |

## Examples

### Form Submission

<Preview>
  <LoadingButton loading={false} loadingText="Saving...">
    Save Changes
  </LoadingButton>
</Preview>

```tsx
function FormExample() {
  const [isSubmitting, setIsSubmitting] = useState(false);

const handleSubmit = async () => {
    setIsSubmitting(true);
    await saveFormData();
    setIsSubmitting(false);
  };

return (
    <LoadingButton
      loading={isSubmitting}
      loadingText="Saving..."
      onClick={handleSubmit}
    >
      Save Changes
    </LoadingButton>
  );
}
```

### Loading State Comparison

<Preview>
  <div className="flex flex-col gap-3">
    <LoadingButton loading={false}>
      Not Loading
    </LoadingButton>

<LoadingButton loading={true}>
      Loading State
    </LoadingButton>
  </div>
</Preview>

```tsx
<LoadingButton loading={false}>
  Not Loading
</LoadingButton>

<LoadingButton loading={true}>
  Loading State
</LoadingButton>
```

### With Loading Text

<Preview>
  <div className="flex flex-col gap-3">
    <LoadingButton loading={true} loadingText="Processing...">
      Process Payment
    </LoadingButton>

<LoadingButton loading={true} loadingText="Uploading...">
      Upload File
    </LoadingButton>
  </div>
</Preview>

```tsx
<LoadingButton
  loading={isProcessing}
  loadingText="Processing..."
>
  Process Payment
</LoadingButton>

<LoadingButton
  loading={isUploading}
  loadingText="Uploading..."
>
  Upload File
</LoadingButton>
```

### Without Loading Text

When `loadingText` is not provided, the button keeps its original label:

<Preview>
  <LoadingButton loading={true}>
    Delete Account
  </LoadingButton>
</Preview>

```tsx
<LoadingButton loading={isDeleting}>
  Delete Account
</LoadingButton>
```

### Spinner Position

<Preview>
  <div className="flex flex-col gap-3">
    <LoadingButton loading={true} spinnerPosition="start" loadingText="Loading...">
      Start Position
    </LoadingButton>

<LoadingButton loading={true} spinnerPosition="end" loadingText="Loading...">
      End Position
    </LoadingButton>
  </div>
</Preview>

```tsx
<LoadingButton
  loading={isProcessing}
  spinnerPosition="start"
  loadingText="Processing..."
>
  Process
</LoadingButton>

<LoadingButton
  loading={isProcessing}
  spinnerPosition="end"
  loadingText="Processing..."
>
  Process
</LoadingButton>
```

### Different Variants

<Preview>
  <div className="flex flex-col gap-3">
    <LoadingButton loading={true} variant="filled">
      Filled Loading
    </LoadingButton>

<LoadingButton loading={true} variant="outlined">
      Outlined Loading
    </LoadingButton>

<LoadingButton loading={true} variant="ghost">
      Ghost Loading
    </LoadingButton>
  </div>
</Preview>

```tsx
<LoadingButton loading={isLoading} variant="filled">
  Filled Loading
</LoadingButton>

<LoadingButton loading={isLoading} variant="outlined">
  Outlined Loading
</LoadingButton>

<LoadingButton loading={isLoading} variant="ghost">
  Ghost Loading
</LoadingButton>
```

### Different Sizes

<Preview>
  <div className="flex items-center gap-3">
    <LoadingButton loading={true} size="sm">
      Small
    </LoadingButton>

<LoadingButton loading={true} size="md">
      Medium
    </LoadingButton>

<LoadingButton loading={true} size="lg">
      Large
    </LoadingButton>
  </div>
</Preview>

```tsx
<LoadingButton loading={isLoading} size="sm">Small</LoadingButton>
<LoadingButton loading={isLoading} size="md">Medium</LoadingButton>
<LoadingButton loading={isLoading} size="lg">Large</LoadingButton>
```

### Async Operation Example

```tsx
'use client';

import { useState } from 'react';
import { LoadingButton } from '@geckoui/geckoui';

function DownloadReport() {
  const [isDownloading, setIsDownloading] = useState(false);

return (
    <LoadingButton
      loading={isDownloading}
      loadingText="Downloading..."
      onClick={handleDownload}
      variant="outlined"
      size="lg"
    >
      Download Report
    </LoadingButton>
  );
}
```

## Behavior

### Loading State

When `loading={true}`:

* Button becomes disabled automatically
* Spinner is displayed (at start or end position)
* Optional loading text replaces the original content
* User interaction is prevented

### Content Display

The button content follows this priority:

1. If `loading={true}` and `loadingText` is provided → shows `loadingText`
2. If `loading={true}` and `loadingText` is not provided → keeps original `children`
3. If `loading={false}` → shows original `children`

## Accessibility

* Inherits all accessibility features from Button component
* Automatically disabled during loading state
* Spinner provides visual feedback
* Loading text provides clear status indication
* Works with screen readers

## Styling

The component uses BEM-style class names:

* `GeckoUILoadingButton` - Main container class
* `GeckoUILoadingButton--{variant}` - Variant modifier
* `GeckoUILoadingButton--{variant}-{color}` - Combined variant and color
* `GeckoUILoadingButton--size-{size}` - Size modifier
* `GeckoUILoadingButton--loading` - Applied during loading state
* `GeckoUILoadingButton--{variant}-loading` - Variant-specific loading state

## Dependencies

This component uses the internal `Spinner` component for the loading animation.

## Related Components

* [Button](/docs/button) - Base button component
* [Spinner](/docs/spinner) - Loading spinner component

# Markdown

import { Markdown } from '@geckoui/geckoui';
import { BasicMarkdownExample, WithTableExample, WithTaskListExample, AsyncRenderingExample, WithErrorHandlingExample, SanitizedContentExample, CustomElementExample, RichContentExample } from '@/components/examples/markdown-examples';

# Markdown

Renders formatted markdown text as HTML with support for both synchronous and asynchronous rendering. Features GitHub Flavored Markdown (GFM), code syntax highlighting, tables, task lists, and optional HTML sanitization for user-generated content.

## Installation

```tsx
import { Markdown } from '@geckoui/geckoui';
```

## Basic Usage

```tsx
'use client';

import { Markdown } from '@geckoui/geckoui';

function Example() {
  const content = `
## Welcome to Markdown

This is a **bold** statement and this is *italic*.

### Features

- GitHub Flavored Markdown (GFM)
- Tables, task lists, strikethrough
- Code syntax highlighting

### Code Example

\`\`\`javascript
function greet(name) {
  console.log(\`Hello, \${name}!\`);
}
\`\`\`
  `;

return <Markdown className="prose prose-sm max-w-none">{content}</Markdown>;
}
```

## Props API

| Prop                | Type                                 | Default        | Description                            |
| ------------------- | ------------------------------------ | -------------- | -------------------------------------- |
| `children`          | `string`                             | -              | Markdown content to render (required)  |
| `as`                | `keyof JSX.IntrinsicElements`        | `"div"`        | HTML element to wrap content           |
| `async`             | `boolean`                            | `false`        | Enable asynchronous rendering          |
| `sanitize`          | `boolean`                            | `true`         | Sanitize HTML to prevent XSS attacks   |
| `renderPlaceholder` | `ReactNode \| FC`                    | -              | Component to show during async loading |
| `renderError`       | `ReactNode \| FC<{message: string}>` | `<InputError>` | Custom error component                 |
| `className`         | `string`                             | -              | Additional CSS classes                 |

## Supported Markdown Features

The component uses [unified](https://unifiedjs.com/) with the following plugins:

* **remark-gfm**: GitHub Flavored Markdown (tables, task lists, strikethrough)
* **remark-math**: Math expressions
* **remark-directive**: Custom directives
* **remark-frontmatter**: YAML frontmatter
* **rehype-raw**: HTML in markdown
* **rehype-sanitize**: HTML sanitization (when `sanitize={true}`)
* **rehype-format**: Pretty HTML output

## Examples

### Tables

GFM tables are fully supported:

```tsx
const content = `
## Product Comparison

| Feature | Basic | Pro | Enterprise |
|---------|-------|-----|------------|
| Users | 5 | 50 | Unlimited |
| Storage | 10GB | 100GB | 1TB |
| Support | Email | Priority | 24/7 Phone |
| Price | $9/mo | $49/mo | Custom |
`;

<Markdown className="prose">{content}</Markdown>
```

### Task Lists

Interactive checkbox lists:

```tsx
const content = `
## Project Checklist

### Phase 1: Design
- [x] Wireframes
- [x] Design system
- [x] User flows

### Phase 2: Development
- [x] Backend API
- [x] Frontend components
- [ ] Integration tests
- [ ] E2E tests
`;

<Markdown className="prose">{content}</Markdown>
```

**When to use `async`**:

* Processing large markdown files
* Preventing UI blocking during rendering

**Behavior**:

* Shows `renderPlaceholder` while processing
* Updates when `children` changes
* Handles errors gracefully

### Error Handling

Customize error display:

```tsx
import { Markdown, Alert } from '@geckoui/geckoui';

<Markdown
  renderError={({ message }) => <Alert variant="error">Error: {message}</Alert>}
  className="prose"
>
  {content}
</Markdown>
```

**Default Behavior**:

* Without `renderError`: Shows `<InputError>` with error message
* With `renderError`: Renders your custom component
* Error component receives `message` prop

### Sanitized User Content

Protect against XSS attacks in user-generated content:

```tsx
<Markdown sanitize className="prose">
  {userGeneratedMarkdown}
</Markdown>
```

**What gets sanitized**:

* `<script>` tags removed
* `onclick` and other event handlers removed
* `javascript:` URLs blocked
* Potentially dangerous attributes stripped
* Markdown formatting preserved

**Important**: Always use `sanitize={true}` for user-generated content!

### Custom Wrapper Element

Use semantic HTML elements:

```tsx
<Markdown as="article" className="prose">
  {content}
</Markdown>
```

## Performance Considerations

### Sync vs Async

**Synchronous (default)**:

* Blocks rendering until complete
* Use for small/medium content
* No loading state needed
* Simpler code

**Asynchronous**:

* Non-blocking rendering
* Use for large content (>10KB)
* Requires loading state
* Better perceived performance

```tsx
// Small content: use sync (default)
<Markdown>{smallContent}</Markdown>

// Large content: use async
<Markdown async renderPlaceholder={<Spinner />}>
  {largeContent}
</Markdown>
```

## Security Best Practices

1. **Always sanitize user content**:
   ```tsx
   <Markdown sanitize>{userContent}</Markdown>
   ```

2. **Validate content sources**:
   ```tsx
   // ✅ Safe: Your own content
   <Markdown>{yourContent}</Markdown>

// ❌ Unsafe: Untrusted user content without sanitization
   <Markdown sanitize={false}>{untrustedContent}</Markdown>

// ✅ Safe: Sanitized user content
   <Markdown sanitize>{untrustedContent}</Markdown>
   ```

3. **Content Security Policy**: Add CSP headers to prevent script injection

4. **Rate limiting**: Limit how much content users can submit

## Accessibility

* Semantic HTML structure (headings, lists, tables)
* Proper heading hierarchy (h1, h2, h3...)
* Alt text for images (if included in markdown)
* Table headers for screen readers
* Focus management for interactive elements

## TypeScript

### Basic Usage

```tsx
import { Markdown } from '@geckoui/geckoui';

const content: string = '## Hello';

<Markdown>{content}</Markdown>
```

### With Custom Element

```tsx
import type { MarkdownProps } from '@geckoui/geckoui';

const MyMarkdown: React.FC<MarkdownProps<'article'>> = (props) => {
  return <Markdown as="article" {...props} />;
};
```

### With Error Handler

```tsx
const errorHandler: React.FC<{ message: string }> = ({ message }) => (
  <div className="error">{message}</div>
);

<Markdown renderError={errorHandler}>{content}</Markdown>
```

## Styling

The component uses the class name `GeckoUIMarkdown`. You can target it in your CSS to apply custom styles:

```css
.GeckoUIMarkdown {
  /* Your custom styles */
}
```

### Large content performance

For very large markdown files (>100KB):

1. Use `async={true}`
2. Consider code splitting
3. Implement pagination
4. Use virtual scrolling

## Related Components

* [MermaidDiagram](/docs/mermaid-diagram) - Render diagrams from markdown
* [Alert](/docs/alert) - Error handling UI

## Related Hooks

* [useMarkdown](#) - Underlying hook for custom implementations

# Menu

import { Menu, MenuButton, MenuItem, MenuItems, MenuSeparator, MenuSection, MenuHeading, Button } from '@geckoui/geckoui';
import { BasicMenuExample, WithIconsExample, WithSectionsExample, DisabledItemsExample, CustomButtonExample, AnchorPositionExample } from '@/components/examples/menu-examples';

# Menu

A styled wrapper around HeadlessUI's Menu component for creating accessible, keyboard-navigable dropdown menus and action lists. Provides pre-styled components with full HeadlessUI functionality for building complex menu patterns.

## Installation

```tsx
import {
  Menu,
  MenuButton,
  MenuItem,
  MenuItems,
  MenuSeparator,
  MenuSection,
  MenuHeading
} from '@geckoui/geckoui';
```

## Basic Usage

```tsx
import { Menu, MenuButton, MenuItem, MenuItems } from '@geckoui/geckoui';

function Example() {
  return (
    <Menu>
      <MenuButton as="button">Options</MenuButton>
      <MenuItems anchor="bottom start" className="w-48">
        <MenuItem onClick={() => console.log('Edit')}>
          Edit
        </MenuItem>
        <MenuItem onClick={() => console.log('Duplicate')}>
          Duplicate
        </MenuItem>
        <MenuItem onClick={() => console.log('Delete')}>
          Delete
        </MenuItem>
      </MenuItems>
    </Menu>
  );
}
```

## Components

### Menu

Root container component that manages menu state.

```tsx
<Menu>{/* MenuButton and MenuItems */}</Menu>
```

### MenuButton

Trigger element that opens the menu. Supports polymorphic rendering via the `as` prop.

```tsx
<MenuButton as="button">Click me</MenuButton>
<MenuButton as={CustomButton}>Custom Button</MenuButton>
```

### MenuItems

Container for menu options. Handles positioning and animations.

| Prop        | Type                 | Default | Description                      |
| ----------- | -------------------- | ------- | -------------------------------- |
| `anchor`    | `Placement`          | -       | Menu position relative to button |
| `as`        | `ElementType`        | `'div'` | Element type to render as        |
| `className` | `string \| Function` | -       | CSS class or render function     |

### MenuItem

Individual selectable option within the menu.

| Prop       | Type                    | Description                        |
| ---------- | ----------------------- | ---------------------------------- |
| `as`       | `ElementType`           | Element type (default: `'button'`) |
| `disabled` | `boolean`               | Disable the menu item              |
| `onClick`  | `() => void`            | Click handler                      |
| `children` | `ReactNode \| Function` | Content or render function         |

Render function receives: `{ focus: boolean, disabled: boolean }`

### MenuSeparator

Visual divider between menu groups or items.

```tsx
<MenuSeparator className="my-1 border-t" />
```

### MenuSection

Groups related menu items together under a heading.

```tsx
<MenuSection>
  <MenuHeading>Section Title</MenuHeading>
  <MenuItem>Item 1</MenuItem>
  <MenuItem>Item 2</MenuItem>
</MenuSection>
```

### MenuHeading

Non-interactive header within menu sections.

```tsx
<MenuHeading className="px-3 py-2 text-xs font-semibold">
  Section Title
</MenuHeading>
```

## Examples

### With Icons

```tsx
import { Edit, Copy, Trash } from 'lucide-react';

<Menu>
  <MenuButton as="button">Actions</MenuButton>
  <MenuItems anchor="bottom start" className="w-48">
    <MenuItem onClick={() => console.log('Edit')}>
      <div className="flex items-center gap-3">
        <Edit className="size-4" />
        <span>Edit</span>
      </div>
    </MenuItem>
    <MenuItem onClick={() => console.log('Delete')}>
      <div className="flex items-center gap-3">
        <Trash className="size-4 text-red-600" />
        <span className="text-red-600">Delete</span>
      </div>
    </MenuItem>
  </MenuItems>
</Menu>
```

### With Sections and Separators

```tsx
<Menu>
  <MenuButton as="button">More Actions</MenuButton>
  <MenuItems anchor="bottom start" className="w-56">
    <MenuSection>
      <MenuHeading className="text-xs font-semibold text-gray-500 uppercase">
        File Actions
      </MenuHeading>
      <MenuItem onClick={() => console.log('Download')}>
        <div className="flex items-center gap-3">
          <Download className="size-4" />
          <span>Download</span>
        </div>
      </MenuItem>
      <MenuItem onClick={() => console.log('Share')}>
        <div className="flex items-center gap-3">
          <Share className="size-4" />
          <span>Share</span>
        </div>
      </MenuItem>
    </MenuSection>

<MenuSection>
      <MenuHeading className="text-xs font-semibold text-gray-500 uppercase">
        Manage
      </MenuHeading>
      <MenuItem onClick={() => console.log('Settings')}>
        Settings
      </MenuItem>
      <MenuItem onClick={() => console.log('Delete')}>
        Delete
      </MenuItem>
    </MenuSection>
  </MenuItems>
</Menu>
```

### Disabled Items

```tsx
<Menu>
  <MenuButton as="button">Actions</MenuButton>
  <MenuItems anchor="bottom start" className="w-48">
    <MenuItem onClick={() => console.log('Available')}>
      Available Action
    </MenuItem>
    <MenuItem disabled>
      {({ disabled }) => (
        <span className={disabled ? 'opacity-50' : ''}>
          Disabled Action
        </span>
      )}
    </MenuItem>
    <MenuItem onClick={() => console.log('Another')}>
      Another Action
    </MenuItem>
  </MenuItems>
</Menu>
```

### Custom Button Component

```tsx
import { Button } from '@geckoui/geckoui';

<Menu>
  <MenuButton as={Button} variant="filled">
    User Menu
  </MenuButton>
  <MenuItems anchor="bottom end" className="w-48 mt-2">
    <MenuItem onClick={() => console.log('Profile')}>Profile</MenuItem>
    <MenuItem onClick={() => console.log('Settings')}>Settings</MenuItem>
    <MenuSeparator className="my-1 border-t" />
    <MenuItem onClick={() => console.log('Logout')}>
      <span className="text-red-600">Logout</span>
    </MenuItem>
  </MenuItems>
</Menu>
```

### Anchor Positioning

```tsx
// Opens upward
<Menu>
  <MenuButton as="button">Top Start</MenuButton>
  <MenuItems anchor="top start" className="w-40 mb-2">
    <MenuItem>Option 1</MenuItem>
    <MenuItem>Option 2</MenuItem>
  </MenuItems>
</Menu>

// Aligns to right edge
<Menu>
  <MenuButton as="button">Bottom End</MenuButton>
  <MenuItems anchor="bottom end" className="w-40 mt-2">
    <MenuItem>Option 1</MenuItem>
    <MenuItem>Option 2</MenuItem>
  </MenuItems>
</Menu>
```

## Render Functions

Both `MenuItem` and class names can use render functions to access state:

### MenuItem Render Function

```tsx
<MenuItem onClick={handleClick}>
  {({ focus, disabled }) => (
    <span className={`
      ${focus ? 'font-medium' : ''}
      ${disabled ? 'opacity-50' : ''}
    `}>
      {focus ? '→ ' : ''}Menu Item
    </span>
  )}
</MenuItem>
```

### ClassName Render Function

```tsx
<MenuItem
  className={({ focus, disabled }) => `
    ${focus ? 'font-medium' : ''}
    ${disabled ? 'opacity-50 cursor-not-allowed' : ''}
  `}
>
  Menu Item
</MenuItem>
```

## Keyboard Navigation

* **Click/Space/Enter**: Toggle menu
* **Arrow Up/Down**: Navigate items
* **Home/End**: Jump to first/last item
* **Escape**: Close menu
* **Tab**: Close menu and move focus
* **Type**: Search items by typing

## Anchor Positions

Available anchor positions:

* `"bottom start"` - Below button, aligned to left
* `"bottom"` - Below button, centered
* `"bottom end"` - Below button, aligned to right
* `"top start"` - Above button, aligned to left
* `"top"` - Above button, centered
* `"top end"` - Above button, aligned to right

## Styling

The component uses BEM-style class names:

* `GeckoUIMenu__button` - Menu button
* `GeckoUIMenu__items` - Menu items container
* `GeckoUIMenu__item` - Individual menu item

Additional styling should be applied via the `className` prop.

## HeadlessUI Documentation

This component wraps HeadlessUI's Menu. For complete API documentation, see:
[HeadlessUI Menu Documentation](https://headlessui.com/react/menu)

## Accessibility

* Fully keyboard navigable
* ARIA attributes automatically applied
* Focus management
* Screen reader support
* Automatic ID generation
* Type-to-search functionality

## Related Components

* [Dropdown](/docs/dropdown) - Simplified dropdown for common use cases
* [Select](/docs/select) - Form select input
* [Button](/docs/button) - Standalone button component

# Mermaid Diagram

import { MermaidDiagram } from '@geckoui/geckoui';
import { FlowchartExample } from '@/components/examples/mermaid-diagram-examples';

# Mermaid Diagram

Renders diagrams from Mermaid syntax with automatic loading and error state management. Supports flowcharts, sequence diagrams, class diagrams, state diagrams, Gantt charts, and all other Mermaid diagram types.

## Installation

```tsx
import { MermaidDiagram } from '@geckoui/geckoui';
```

## Basic Usage

```tsx
'use client';

import { MermaidDiagram, Spinner } from '@geckoui/geckoui';

function Example() {
  const diagram = `
flowchart LR
    Start[User Login] --> Auth{Authenticated?}
    Auth -->|Yes| Dashboard[Show Dashboard]
    Auth -->|No| Login[Login Page]
    Login --> Auth
  `;

return <MermaidDiagram placeholder={<Spinner />}>{diagram}</MermaidDiagram>;
}
```

## Props API

| Prop          | Type                                 | Default        | Description                       |
| ------------- | ------------------------------------ | -------------- | --------------------------------- |
| `children`    | `string`                             | -              | Mermaid diagram syntax (required) |
| `placeholder` | `ReactNode \| FC`                    | -              | Component to show during loading  |
| `renderError` | `ReactNode \| FC<{message: string}>` | `<InputError>` | Custom error component            |
| `className`   | `string`                             | -              | Additional CSS classes for SVG    |
| `width`       | `string \| number`                   | -              | SVG width (overrides default)     |
| `height`      | `string \| number`                   | -              | SVG height (overrides default)    |

**Additional**: Accepts all standard SVG props except `id`, `viewBox`, and `dangerouslySetInnerHTML`.

## Performance

The component automatically handles rendering performance:

1. **Async rendering**: Diagrams render without blocking UI
2. **Loading states**: Shows placeholder during processing
3. **Error boundaries**: Catches and displays syntax errors
4. **DOM cleanup**: Removes temporary elements after rendering
5. **Validation**: Validates syntax before rendering

## Browser Support

Requires browsers that support:

* SVG rendering
* ES6+ JavaScript
* Async/await

Works in all modern browsers (Chrome, Firefox, Safari, Edge).

## Troubleshooting

### Diagram not rendering

1. Check syntax validity
2. Ensure `children` is a string
3. Look for console errors
4. Verify Mermaid version compatibility

### Syntax errors

Use Mermaid's [Live Editor](https://mermaid.live/) to validate syntax.

### Performance issues

For complex diagrams:

* Simplify node count
* Split into multiple diagrams
* Use appropriate diagram type

### Styling issues

The SVG inherits the original Mermaid classes. Use `className` to add custom styles:

```tsx
<MermaidDiagram className="my-custom-styles">{diagram}</MermaidDiagram>
```

## TypeScript

```tsx
import type { MermaidDiagramProps } from '@geckoui/geckoui';

const MyDiagram: React.FC<{ syntax: string }> = ({ syntax }) => {
  return <MermaidDiagram placeholder={<Spinner />}>{syntax}</MermaidDiagram>;
};
```

## Accessibility

* SVG output is screen reader accessible
* Use descriptive node labels
* Provide text alternatives for complex diagrams
* Ensure sufficient color contrast
* Add ARIA labels if needed:

```tsx
<MermaidDiagram aria-label="System architecture diagram">{diagram}</MermaidDiagram>
```

## Related Components

* [Markdown](/docs/markdown) - Render markdown with embedded diagrams

## Related Hooks

* [useMermaidDiagram](#) - Underlying hook for custom implementations

## Resources

* [Mermaid Documentation](https://mermaid.js.org/)
* [Mermaid Live Editor](https://mermaid.live/)
* [Diagram Syntax Examples](https://mermaid.js.org/intro/)

# OTP Input

import { OTPInput } from '@geckoui/geckoui';
import { BasicOTPInputExample, TwoFactorAuthExample, SMSVerificationExample, AlphanumericCodeExample, CustomLengthExample, DisabledOTPExample } from '@/components/examples/otp-input-examples';

# OTP Input

A segmented input component for entering one-time passwords or verification codes. Each digit is displayed in a separate box with automatic focus management, keyboard navigation, and support for both numeric-only and alphanumeric input.

## Installation

```tsx
import { OTPInput } from '@geckoui/geckoui';
```

## Basic Usage

```tsx
import { useState } from 'react';

function Example() {
  const [code, setCode] = useState('');

return (
    <div className="max-w-sm">
      <OTPInput
        value={code}
        onChange={setCode}
      />
    </div>
  );
}
```

## Props API

| Prop             | Type                      | Default | Description                            |
| ---------------- | ------------------------- | ------- | -------------------------------------- |
| `value`          | `string`                  | -       | Value of the OTP input (required)      |
| `onChange`       | `(value: string) => void` | -       | Callback when value changes (required) |
| `length`         | `number`                  | `6`     | Number of input boxes to display       |
| `numberOnly`     | `boolean`                 | `true`  | Only allow numeric input               |
| `onOTPComplete`  | `(value: string) => void` | -       | Callback when all digits are filled    |
| `aspectRatio`    | `string \| number`        | `0.94`  | Aspect ratio of each input box         |
| `className`      | `string`                  | -       | CSS class for the wrapper              |
| `inputClassName` | `string`                  | -       | CSS class for individual inputs        |
| `disabled`       | `boolean`                 | `false` | Disable the input                      |
| `onBlur`         | `(e: FocusEvent) => void` | -       | Callback when input loses focus        |

## Examples

### Two-Factor Authentication

```tsx
function TwoFactorAuth() {
  const [code, setCode] = useState('');

return (
    <div>
      <h3>Enter verification code</h3>
      <OTPInput
        value={code}
        onChange={setCode}
        length={6}
        numberOnly
        onOTPComplete={async (code) => {
          await verifyTwoFactorCode(code);
        }}
      />
    </div>
  );
}
```

### SMS Verification

```tsx
function SMSVerification() {
  const [smsCode, setSmsCode] = useState('');
  const [isVerifying, setIsVerifying] = useState(false);

return (
    <div>
      <p>Enter the 4-digit code sent to your phone</p>
      <OTPInput
        value={smsCode}
        onChange={setSmsCode}
        length={4}
        aspectRatio={1}
        className="max-w-[180px]"
        onOTPComplete={async (code) => {
          setIsVerifying(true);
          await submitVerification(code);
          setIsVerifying(false);
        }}
        disabled={isVerifying}
      />
    </div>
  );
}
```

### Alphanumeric Code

```tsx
function ActivationCode() {
  const [activationCode, setActivationCode] = useState('');

return (
    <OTPInput
      value={activationCode}
      onChange={setActivationCode}
      length={8}
      numberOnly={false}
      className="gap-2"
      inputClassName="border-2 rounded-md"
    />
  );
}
```

### Custom Length

```tsx
function CustomLength() {
  const [pin, setPin] = useState('');
  const [longCode, setLongCode] = useState('');

return (
    <>
      <OTPInput
        value={pin}
        onChange={setPin}
        length={4}
        className="max-w-[180px]"
      />

<OTPInput
        value={longCode}
        onChange={setLongCode}
        length={8}
      />
    </>
  );
}
```

### Disabled State

```tsx
<OTPInput
  value="123456"
  onChange={setCode}
  disabled
/>
```

## Behavior

### Auto-Focus Management

* Automatically focuses the next empty box when a digit is entered
* Automatically focuses the previous box when backspace/delete is pressed
* Clicking on the component focuses the first empty box

### Keyboard Navigation

* **Number keys**: Enter digits (when `numberOnly={true}`)
* **Alphanumeric**: All characters allowed (when `numberOnly={false}`)
* **Backspace/Delete**: Remove last digit and focus previous box
* **Tab**: Move focus to next element
* **Enter**: Prevent form submission on incomplete input

### OTP Complete Callback

The `onOTPComplete` callback fires when all boxes are filled:

```tsx
<OTPInput
  value={code}
  onChange={setCode}
  length={6}
  onOTPComplete={async (completeCode) => {
    // Automatically triggered when all 6 digits are entered
    console.log('Complete code:', completeCode);
    await verifyCode(completeCode);
  }}
/>
```

## Accessibility

* Each input box is individually focusable
* Keyboard navigation fully supported
* Works with screen readers
* Disabled state properly communicated
* Automatic focus management improves UX

## Styling

The component uses BEM-style class names:

* `GeckoUIOTPInput` - Main container
* `GeckoUIOTPInput--enabled` - Applied when not disabled
* `GeckoUIOTPInput--disabled` - Applied when disabled
* `GeckoUIOTPInput__input` - Individual input box
* `GeckoUIOTPInput__overlay-button` - Invisible button for click handling

## Custom Styling

Override styles using `className` for the container or `inputClassName` for individual boxes:

```tsx
<OTPInput
  value={code}
  onChange={setCode}
  className="gap-4"
  inputClassName="rounded-lg border-2 border-blue-500"
/>
```

## Related Components

* [Input](/docs/input) - Single-line text input
* [RHFOTPInput](/docs/rhf-otp-input) - React Hook Form integration

# Pagination

import { Pagination } from '@geckoui/geckoui';
import { BasicPaginationExample, LargePaginationExample, CenteredPaginationExample, RightAlignedPaginationExample, WithDataFetchingExample, APIIntegrationExample } from '@/components/examples/pagination-examples';

# Pagination

A pagination component for navigating through multiple pages of content. Features intelligent ellipsis display for large page counts, previous/next navigation, and automatically hides when there's only one page.

## Installation

```tsx
import { Pagination } from '@geckoui/geckoui';
```

## Basic Usage

```tsx
'use client';

import { useState } from 'react';
import { Pagination } from '@geckoui/geckoui';

function Example() {
  const [page, setPage] = useState(1);

return (
    <Pagination
      currentPage={page}
      totalPages={10}
      onChange={setPage}
    />
  );
}
```

## Props API

| Prop          | Type                     | Default | Description                           |
| ------------- | ------------------------ | ------- | ------------------------------------- |
| `currentPage` | `number`                 | -       | Current active page (required)        |
| `totalPages`  | `number`                 | -       | Total number of pages (required)      |
| `onChange`    | `(page: number) => void` | -       | Callback when page changes (required) |
| `className`   | `string`                 | -       | Additional CSS classes                |

## Examples

### Large Page Count

The component automatically shows ellipsis for large page counts:

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

<Pagination
  currentPage={page}
  totalPages={100}
  onChange={setPage}
/>
```

**Ellipsis Logic**:

* Shows all pages if total ≤ 7
* Shows ellipsis when current page is near start/middle/end
* Always shows first and last page numbers

### Centered Alignment

```tsx
<Pagination
  currentPage={page}
  totalPages={20}
  onChange={setPage}
  className="justify-center"
/>
```

### Right Aligned

```tsx
<Pagination
  currentPage={page}
  totalPages={15}
  onChange={setPage}
  className="justify-end"
/>
```

### With Data Fetching

```tsx
const [page, setPage] = useState(1);
const [loading, setLoading] = useState(false);

const items = [...]; // Your data array
const itemsPerPage = 3;
const totalPages = Math.ceil(items.length / itemsPerPage);

const handlePageChange = (newPage: number) => {
  setLoading(true);
  setPage(newPage);
  // Simulate API call
  setTimeout(() => setLoading(false), 300);
};

// Calculate current page items
const startIndex = (page - 1) * itemsPerPage;
const currentItems = items.slice(startIndex, startIndex + itemsPerPage);

<div>
  <div className="border rounded-md p-4">
    {loading ? (
      <div>Loading...</div>
    ) : (
      <ul>
        {currentItems.map((item, index) => (
          <li key={index}>{item}</li>
        ))}
      </ul>
    )}
  </div>
  <Pagination
    currentPage={page}
    totalPages={totalPages}
    onChange={handlePageChange}
  />
</div>
```

### API Integration

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

// From API response
const totalItems = 250;
const itemsPerPage = 25;
const totalPages = Math.ceil(totalItems / itemsPerPage);

const handlePageChange = (newPage: number) => {
  setPage(newPage);
  fetchData(`/api/items?page=${newPage}&limit=${itemsPerPage}`);
};

<div>
  <p>
    Showing {(page - 1) * itemsPerPage + 1}-
    {Math.min(page * itemsPerPage, totalItems)} of {totalItems} items
  </p>
  <Pagination
    currentPage={page}
    totalPages={totalPages}
    onChange={handlePageChange}
  />
</div>
```

## Ellipsis Display Logic

The pagination intelligently displays page numbers based on the current page:

### Small Page Count (≤ 7 pages)

Shows all pages: `[1] [2] [3] [4] [5] [6] [7]`

### Current Page Near Start (pages 1-4)

`[1] [2] [3] [4] [5] ... [100]`

### Current Page Near End (last 4 pages)

`[1] ... [96] [97] [98] [99] [100]`

### Current Page in Middle

`[1] ... [49] [50] [51] ... [100]`

## Behavior

### Auto-Hide on Single Page

The component returns `null` when `totalPages <= 1`, automatically hiding itself.

```tsx
// This won't render anything
<Pagination currentPage={1} totalPages={1} onChange={setPage} />
```

### Navigation Controls

**Previous Button**:

* Disabled on first page
* Decrements current page by 1
* Shows left arrow icon

**Next Button**:

* Disabled on last page
* Increments current page by 1
* Shows right arrow icon

**Page Numbers**:

* Click to jump directly to that page
* Current page is highlighted
* Ellipsis buttons are disabled

### Page Counter

Displays current page / total pages (e.g., "5 / 10") for quick reference.

## Styling

The component uses BEM-style class names:

* `GeckoUIPagination` - Main container
* `GeckoUIPagination__arrow` - Previous/Next buttons
* `GeckoUIPagination__arrow--previous` - Previous arrow icon
* `GeckoUIPagination__arrow--next` - Next arrow icon
* `GeckoUIPagination__page-count` - Page counter display
* `GeckoUIPagination__page-buttons` - Page number buttons container
* `GeckoUIPagination__page-button` - Individual page button
* `GeckoUIPagination__page-button--active` - Active page
* `GeckoUIPagination__page-button--ellipsis` - Ellipsis button

## Accessibility

* Semantic button elements for navigation
* Disabled state for unavailable actions
* Keyboard navigable (Tab to focus, Enter/Space to activate)
* Clear visual indication of current page

## Related Components

* [Spinner](/docs/spinner) - Show loading state during pagination

# Radio

import { Radio } from '@geckoui/geckoui';
import { RadioBasicExample, RadioWithDescriptionsExample, RadioHorizontalExample, RadioDisabledExample } from '@/components/examples/radio-examples';

# Radio

A styled radio button component for creating mutually exclusive selection groups.

## Installation

```tsx
import { Radio } from '@geckoui/geckoui';
```

## Basic Usage

```tsx
import { useState } from 'react';

function Example() {
  const [selected, setSelected] = useState('option1');

return (
    <div>
      <label>
        <Radio
          name="options"
          value="option1"
          checked={selected === 'option1'}
          onChange={(e) => setSelected(e.target.value)}
        />
        Option 1
      </label>
      <label>
        <Radio
          name="options"
          value="option2"
          checked={selected === 'option2'}
          onChange={(e) => setSelected(e.target.value)}
        />
        Option 2
      </label>
    </div>
  );
}
```

## Props API

| Prop        | Type                  | Default | Description                              |
| ----------- | --------------------- | ------- | ---------------------------------------- |
| `name`      | `string`              | -       | Radio group name (required for grouping) |
| `value`     | `string`              | -       | Value of this radio option               |
| `checked`   | `boolean`             | -       | Whether this radio is selected           |
| `disabled`  | `boolean`             | `false` | Disable the radio button                 |
| `onChange`  | `ChangeEventHandler`  | -       | Callback when selection changes          |
| `className` | `string`              | -       | CSS class for styling                    |
| ...rest     | `InputHTMLAttributes` | -       | All standard HTML input attributes       |

## Examples

### Radio Group with Descriptions

```tsx
function PaymentMethod() {
  const [selected, setSelected] = useState("free");

const options = [
    { value: "free", title: "Free Plan", desc: "Perfect for trying out" },
    { value: "pro", title: "Pro Plan", desc: "$9/month - Most popular" },
    { value: "enterprise", title: "Enterprise", desc: "Contact us for pricing" }
  ];

return (
    <div className="flex flex-col gap-3">
      {options.map((option) => (
        <label
          key={option.value}
          className="flex items-start gap-3 p-3 border rounded-lg cursor-pointer hover:bg-gray-50 dark:hover:bg-gray-800">
          <Radio
            name="plan"
            className="mt-2"
            value={option.value}
            checked={selected === option.value}
            onChange={(e) => setSelected(e.target.value)}
          />
          <div>
            <div className="flex items-center font-medium">
              <span>{option.title}</span>
            </div>
            <div className="text-sm text-gray-500">{option.desc}</div>
          </div>
        </label>
      ))}
    </div>
  );
}
```

### Disabled State

```tsx
<div className="space-y-2">
  <label className="flex items-center gap-2">
    <Radio name="status" value="enabled" checked />
    <span>Enabled</span>
  </label>
  <label className="flex items-center gap-2 opacity-50">
    <Radio name="status" value="disabled" disabled />
    <span>Disabled</span>
  </label>
</div>
```

### Horizontal Layout

```tsx
function SizeSelector() {
  const [size, setSize] = useState('M');
  const sizes = ['XS', 'S', 'M', 'L', 'XL'];

return (
    <div className="flex gap-4">
      {sizes.map(s => (
        <label key={s} className="flex items-center gap-2">
          <Radio
            name="size"
            value={s}
            checked={size === s}
            onChange={(e) => setSize(e.target.value)}
          />
          <span>{s}</span>
        </label>
      ))}
    </div>
  );
}
```

## Grouping Radio Buttons

Radio buttons with the same `name` prop are automatically grouped. Only one radio button in a group can be selected at a time.

```tsx
// All these radios are grouped by name="color"
<Radio name="color" value="red" />
<Radio name="color" value="blue" />
<Radio name="color" value="green" />
```

## Accessibility

* Fully keyboard navigable
* Arrow keys navigate between radio buttons in the same group
* Space key selects the focused radio
* Works with screen readers
* Disabled state properly communicated

## Styling

The component uses the class name `GeckoUIRadio`. Override styles using the `className` prop:

```css
.GeckoUIRadio {
  /* Your custom styles */
}
```

## Related Components

* [Checkbox](/docs/checkbox) - For multi-select
* [Switch](/docs/switch) - For toggle states
* [Select](/docs/select) - For dropdown selections
* [RHFRadio](/docs/rhf-radio) - React Hook Form integration

# RHFCheckbox

import { RHFCheckbox } from '@geckoui/geckoui';
import {
  SingleCheckboxExample,
  SingleWithUncheckedValueExample,
  MultiSelectExample,
  WithValidationExample,
  WithPartialStateExample,
  WithObjectValuesExample,
  DisabledExample,
  CompleteFormExample
} from '@/components/examples/rhf-checkbox-examples';

# RHFCheckbox

A controlled checkbox component for React Hook Form that preserves value types. Unlike native checkboxes that convert values to strings, this component maintains the original data type. Supports both single-select (like a radio) and multi-select modes with optional indeterminate state.

## Installation

```tsx
import { RHFCheckbox } from '@geckoui/geckoui';
```

## Basic Usage

### Single Checkbox Mode

```tsx
import { useForm, FormProvider } from 'react-hook-form';
import { RHFCheckbox } from '@geckoui/geckoui';

function Example() {
  const methods = useForm({
    defaultValues: {
      agreement: null
    }
  });

return (
    <FormProvider {...methods}>
      <RHFCheckbox
        name="agreement"
        value="agreed"
        label="I agree to the terms and conditions"
        single
      />
    </FormProvider>
  );
}
```

### Multi-Select Mode

```tsx
import { useForm, FormProvider } from 'react-hook-form';
import { RHFCheckbox } from '@geckoui/geckoui';

function Example() {
  const methods = useForm({
    defaultValues: {
      options: []
    }
  });

return (
    <FormProvider {...methods}>
      <div className="flex flex-col gap-3">
        <RHFCheckbox name="options" value="option1" label="Option 1" />
        <RHFCheckbox name="options" value="option2" label="Option 2" />
        <RHFCheckbox name="options" value="option3" label="Option 3" />
      </div>
    </FormProvider>
  );
}
```

## Props API

Extends all props from [Checkbox](/docs/checkbox) component plus:

| Prop             | Type                       | Default       | Description                                                       |
| ---------------- | -------------------------- | ------------- | ----------------------------------------------------------------- |
| `name`           | `string`                   | -             | Field name (required)                                             |
| `control`        | `Control`                  | Auto-injected | Optional: Pass explicitly for nested forms or custom form context |
| `rules`          | `RegisterOptions`          | -             | Inline validation rules                                           |
| `label`          | `ReactNode \| Function`    | -             | Label displayed next to checkbox                                  |
| `labelClassName` | `string`                   | -             | CSS class for the label                                           |
| `value`          | `unknown`                  | -             | Value to set when checked                                         |
| `single`         | `boolean`                  | `false`       | Act as single selection (stores value, not array)                 |
| `uncheckedValue` | `unknown`                  | `null`        | Value when unchecked (only with `single`)                         |
| `partial`        | `boolean \| Function`      | `false`       | Show indeterminate state                                          |
| `onChange`       | `(value: unknown) => void` | -             | Change callback                                                   |
| ...rest          | `CheckboxProps`            | -             | All Checkbox component props                                      |

## Examples

### Single with Custom Unchecked Value

```tsx
<RHFCheckbox
  name="enabled"
  value="yes"
  uncheckedValue="no"
  label="Enable notifications"
  single
/>
```

### With Validation (Zod)

```tsx
import { useForm, FormProvider } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';
import { RHFCheckbox, RHFInputGroup } from '@geckoui/geckoui';

const schema = z.object({
  terms: z.literal('agreed', { message: 'You must agree to the terms' })
});

function Example() {
  const methods = useForm({
    resolver: zodResolver(schema),
    mode: 'onBlur',
    defaultValues: { terms: null }
  });

return (
    <FormProvider {...methods}>
      <RHFInputGroup required>
        <RHFCheckbox
          name="terms"
          value="agreed"
          label="I agree to the terms and conditions"
          single
        />
      </RHFInputGroup>
    </FormProvider>
  );
}
```

### With Partial/Indeterminate State

```tsx
<div className="flex flex-col gap-3">
  <RHFCheckbox
    name="languages"
    value="js"
    partial={({ field }) => {
      const selected = field.value || [];
      return selected.length > 0 && selected.length < 2;
    }}
    label="JavaScript"
  />
  <RHFCheckbox
    name="languages"
    value="ts"
    partial={({ field }) => {
      const selected = field.value || [];
      return selected.length > 0 && selected.length < 2;
    }}
    label="TypeScript"
  />
</div>
```

### With Object Values

```tsx
<RHFCheckbox
  name="settings"
  value={{ feature: 'advanced', enabled: true }}
  label="Enable advanced features"
  single
/>
```

### Disabled State

```tsx
<div className="flex gap-4">
  <RHFCheckbox name="readonly" value="checked" label="Checked & Disabled" disabled />
  <RHFCheckbox name="disabled" value="unchecked" label="Unchecked & Disabled" disabled />
</div>
```

### Complete Form Example

const schema = z.object({
  terms: z.literal('agreed', { message: 'You must agree to the terms' }),
  newsletter: z.string().nullable().optional(),
  interests: z.array(z.string()).min(1, 'Select at least one interest')
});

function FormExample() {
  const methods = useForm({
    resolver: zodResolver(schema),
    mode: 'onBlur',
    defaultValues: {
      terms: null,
      newsletter: null,
      interests: []
    }
  });

return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit(console.log)}>
        <RHFInputGroup required>
          <RHFCheckbox
            name="terms"
            value="agreed"
            label="I agree to the terms and conditions"
            single
          />
        </RHFInputGroup>

<Button type="submit">Submit</Button>
      </form>
    </FormProvider>
  );
}
```

## Inline Rules Validation

For simple validation, use the `rules` prop:

```tsx
<RHFCheckbox
  name="terms"
  value="agreed"
  label="I agree to the terms"
  single
  rules={{ required: 'You must accept the terms' }}
/>
```

For complex forms, we recommend using a schema resolver (Zod, Yup) instead.

## Single vs Multi Mode

### Single Mode (`single={true}`)

* Acts like a radio button
* Stores one value or `uncheckedValue`
* When checked: stores the `value` prop
* When unchecked: stores `uncheckedValue` (default: `null`)

```tsx
// Result: "agreed" or null
<RHFCheckbox name="terms" value="agreed" single />

// Result: "yes" or "no"
<RHFCheckbox name="enabled" value="yes" uncheckedValue="no" single />
```

### Multi Mode (default)

* Stores an array of selected values
* Multiple checkboxes with same `name` create a group
* Each checkbox adds/removes its value from the array

```tsx
// Result: ["option1", "option3"]
<RHFCheckbox name="options" value="option1" label="Option 1" />
<RHFCheckbox name="options" value="option2" label="Option 2" />
<RHFCheckbox name="options" value="option3" label="Option 3" />
```

## Value Type Preservation

Unlike native HTML checkboxes, RHFCheckbox preserves the original value type:

```tsx
// String values
<RHFCheckbox name="plan" value="pro" single />

// Boolean values
<RHFCheckbox name="enabled" value={true} single />

// Number values
<RHFCheckbox name="age" value={18} single />

// Object values
<RHFCheckbox name="settings" value={{ feature: "advanced" }} single />

// Array values
<RHFCheckbox name="data" value={[1, 2, 3]} single />
```

## Indeterminate State

Use the `partial` prop to show an indeterminate state (useful for "select all" scenarios):

```tsx
// Boolean partial
<RHFCheckbox
  name="selectAll"
  value="all"
  partial={someSelected && !allSelected}
  single
/>

// Dynamic partial based on field state
<RHFCheckbox
  name="items"
  value="item1"
  partial={({ field }) => field.value.length > 0 && field.value.length < total}
/>
```

## Error States

RHFCheckbox doesn't apply error styling directly. Use [RHFInputGroup](/docs/rhf-input-group) to display errors:

```tsx
<RHFInputGroup required>
  <RHFCheckbox name="terms" value="agreed" label="I agree" single />
</RHFInputGroup>
```

**Tip**: Use `mode: 'onBlur'` in useForm to validate on blur:

```tsx
const methods = useForm({
  resolver: zodResolver(schema),
  mode: 'onBlur'
});
```

## Accessibility

* Inherits all accessibility features from [Checkbox](/docs/checkbox) component
* Proper ARIA attributes
* Keyboard navigable (Space/Enter to toggle)
* Screen reader compatible
* Disabled state properly communicated

## Related Components

* [Checkbox](/docs/checkbox) - Base checkbox component
* [RHFRadio](/docs/rhf-radio) - Radio button group
* [RHFSwitch](/docs/rhf-switch) - Toggle switch

# RHFController

RHFController is a wrapper around React Hook Form's Controller component that automatically injects the `control` prop from `FormProvider`. This is the foundation for all RHF\* components in Gecko UI.

## Installation

```tsx
import { RHFController } from '@geckoui/geckoui';
```

## Basic Usage

```tsx
import { useForm, FormProvider } from 'react-hook-form';
import { RHFController } from '@geckoui/geckoui';

function Example() {
  const methods = useForm({
    defaultValues: {
      email: ''
    }
  });

return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit(console.log)}>
        <RHFController
          name="email"
          render={({ field }) => (
            <input
              {...field}
              type="email"
              placeholder="Enter email"
            />
          )}
        />
      </form>
    </FormProvider>
  );
}
```

## Props API

Accepts all props from React Hook Form's [Controller](https://react-hook-form.com/api/usecontroller/controller):

| Prop               | Type       | Default       | Description                                                       |
| ------------------ | ---------- | ------------- | ----------------------------------------------------------------- |
| `name`             | `string`   | -             | Field name (required)                                             |
| `control`          | `Control`  | Auto-injected | Optional: Pass explicitly for nested forms or custom form context |
| `render`           | `function` | -             | Render prop function (required)                                   |
| `defaultValue`     | `any`      | -             | Default field value                                               |
| `shouldUnregister` | `boolean`  | `false`       | Unregister field on unmount                                       |

**About `control` prop**: By default, RHFController uses `useFormContext()` to get the control object automatically. Pass it explicitly when you have nested `FormProvider`s and want to connect to a specific form instance.

## Why Use RHFController?

### Without RHFController (Standard RHF)

```tsx
import { Controller, useFormContext } from 'react-hook-form';

function CustomInput() {
  const { control } = useFormContext();

return (
    <Controller
      control={control}  // Must manually get and pass control
      name="email"
      render={({ field }) => <input {...field} />}
    />
  );
}
```

### With RHFController (Gecko UI)

```tsx
import { RHFController } from '@geckoui/geckoui';

function CustomInput() {
  return (
    <RHFController
      name="email"  // control is auto-injected!
      render={({ field }) => <input {...field} />}
    />
  );
}
```

## Examples

### Access Form State

```tsx
<RHFController
  name="password"
  render={({ field, fieldState, formState }) => (
    <div>
      <input {...field} type="password" />
      {fieldState.error && (
        <span>{fieldState.error.message}</span>
      )}
      {formState.isDirty && <span>Unsaved changes</span>}
    </div>
  )}
/>
```

### Custom Component Integration

```tsx
<RHFController
  name="birthDate"
  render={({ field }) => (
    <CustomDatePicker
      value={field.value}
      onChange={field.onChange}
      onBlur={field.onBlur}
    />
  )}
/>
```

### Nested FormProviders

When you have nested forms, pass `control` explicitly to specify which form:

```tsx
function NestedFormsExample() {
  const outerForm = useForm({ defaultValues: { outerField: '' } });
  const innerForm = useForm({ defaultValues: { innerField: '' } });

return (
    <FormProvider {...outerForm}>
      <FormProvider {...innerForm}>
        {/* Uses innerForm's control automatically */}
        <RHFController
          name="innerField"
          render={({ field }) => <input {...field} />}
        />

{/* Explicitly use outerForm's control */}
        <RHFController
          name="outerField"
          control={outerForm.control}
          render={({ field }) => <input {...field} />}
        />
      </FormProvider>
    </FormProvider>
  );
}
```

## When to Use

### Use RHFController When:

* Building custom form components
* Integrating third-party libraries
* Need fine-grained control over field behavior

### Use Pre-built RHF Components When:

* Working with Gecko UI components
* Want automatic error styling
* Need less boilerplate

## Related Components

* [RHFInput](/docs/rhf-input) - Text input wrapper
* [React Hook Form Controller](https://react-hook-form.com) - Official docs

# RHFDateInput

import { RHFDateInput } from '@geckoui/geckoui';
import {
  BasicRHFDateInputExample,
  WithValidationExample,
  WithPrefixSuffixExample,
  WithDateRangeValidationExample,
  DisabledExample,
  WithCustomCallbackExample,
  CompleteFormExample
} from '@/components/examples/rhf-date-input-examples';

# RHFDateInput

A date input component integrated with React Hook Form that automatically displays error states with a red border when validation fails. Accepts and displays dates in MM/DD/YYYY format with automatic formatting as the user types.

## Installation

```tsx
import { RHFDateInput } from '@geckoui/geckoui';
```

## Basic Usage

```tsx
import { useForm, FormProvider } from 'react-hook-form';
import { RHFDateInput } from '@geckoui/geckoui';

function Example() {
  const methods = useForm({
    defaultValues: {
      basicBirthday: ''
    }
  });

return (
    <FormProvider {...methods}>
      <RHFDateInput name="basicBirthday" placeholder="MM/DD/YYYY" format="MM/DD/YYYY" />
    </FormProvider>
  );
}
```

## Props API

Extends all props from [DateInput](/docs/date-input) component plus:

| Prop        | Type                      | Default       | Description                                                       |
| ----------- | ------------------------- | ------------- | ----------------------------------------------------------------- |
| `name`      | `string`                  | -             | Field name (required)                                             |
| `control`   | `Control`                 | Auto-injected | Optional: Pass explicitly for nested forms or custom form context |
| `rules`     | `RegisterOptions`         | -             | Inline validation rules                                           |
| `className` | `string`                  | -             | Additional CSS class name for the input container                 |
| `disabled`  | `boolean`                 | -             | Whether the input is disabled                                     |
| `prefix`    | `ReactNode \| Function`   | -             | Element before input                                              |
| `suffix`    | `ReactNode \| Function`   | -             | Element after input                                               |
| `onChange`  | `(value: string) => void` | -             | Change callback                                                   |
| `onBlur`    | `(value: string) => void` | -             | Blur callback                                                     |

## Examples

### With Validation (Zod)

```tsx
import { useForm, FormProvider } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';
import { RHFDateInput, RHFInputGroup } from '@geckoui/geckoui';

const schema = z.object({
  validationStartDate: z.string()
    .min(1, 'Start date is required')
});

function Example() {
  const methods = useForm({
    resolver: zodResolver(schema),
    mode: 'onBlur',
    defaultValues: { validationStartDate: '' }
  });

return (
    <FormProvider {...methods}>
      <RHFInputGroup label="Start Date" required>
        <RHFDateInput name="validationStartDate" placeholder="MM/DD/YYYY" format="MM/DD/YYYY" />
      </RHFInputGroup>
    </FormProvider>
  );
}
```

### With Prefix and Suffix

```tsx
<RHFDateInput
  name="prefixEventDate"
  placeholder="MM/DD/YYYY"
  format="MM/DD/YYYY"
  prefix={<span className="text-gray-400">📅</span>}
  suffix={<span className="text-gray-400 text-xs">Event Date</span>}
  hideCalendarIcon
/>
```

### With Date Range Validation

```tsx
const today = new Date();
const minDate = new Date(today);
minDate.setFullYear(today.getFullYear() - 100);
const maxDate = new Date(today);

<RHFInputGroup label="Birth Date" required>
  <RHFDateInput name="rangeValidationBirthDate" placeholder="MM/DD/YYYY" format="MM/DD/YYYY" />
</RHFInputGroup>
```

### Disabled State

```tsx
<RHFDateInput name="disabledFixedDate" disabled format="MM/DD/YYYY" />
```

### With Custom Callback

```tsx
const handleDateChange = (value: string) => {
  console.log('Date changed:', value);
};

<RHFDateInput
  name="callbackAppointmentDate"
  placeholder="MM/DD/YYYY"
  format="MM/DD/YYYY"
  onChange={handleDateChange}
/>
```

### Complete Form Example

```tsx
import { useForm, FormProvider } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';
import { RHFInput, RHFDateInput, RHFInputGroup, Button } from '@geckoui/geckoui';

function BookingForm() {
  const methods = useForm({
    resolver: zodResolver(schema),
    mode: 'onBlur',
    defaultValues: {
      formCheckInDate: '',
      formCheckOutDate: '',
      formGuestName: ''
    }
  });

return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit(onSubmit)} className="space-y-4">
        <RHFInputGroup label="Guest Name" required>
          <RHFInput name="formGuestName" placeholder="Enter your name" />
        </RHFInputGroup>

<Button type="submit">Book Now</Button>
      </form>
    </FormProvider>
  );
}
```

## Inline Rules Validation

For simple validation, use the `rules` prop:

```tsx
<RHFDateInput
  name="birthDate"
  rules={{ required: 'Birth date is required' }}
/>
```

For complex forms, we recommend using a schema resolver (Zod, Yup) instead.

## Date Format

RHFDateInput stores and displays dates in **MM/DD/YYYY** format (US date format).

### Formatting Behavior

* Automatically formats input as user types
* Adds slashes after month and day
* Accepts various input formats and normalizes to MM/DD/YYYY
* Stored value in form state is a string in MM/DD/YYYY format

### Validation Pattern

```tsx
const schema = z.object({
  date: z.string()
    .min(1, 'Date is required')
});
```

### Converting to/from Date Objects

```tsx
const dateStringToDate = (dateStr: string): Date => {
  const [month, day, year] = dateStr.split('/').map(Number);
  return new Date(year, month - 1, day);
};

## Error States

RHFDateInput automatically displays error states with:

* Red border via `hasError` prop when `fieldState.error` exists
* No automatic error icon (you must add via suffix prop if desired)

Use [RHFInputGroup](/docs/rhf-input-group) component for label + input + error layout:

```tsx
<RHFInputGroup label="Birth Date" required>
  <RHFDateInput name="basicBirthday" format="MM/DD/YYYY" />
</RHFInputGroup>
```

Or combine with [RHFError](/docs/rhf-error) component manually:

```tsx
<RHFDateInput name="basicBirthday" format="MM/DD/YYYY" />
<RHFError name="basicBirthday" />
```

**Tip**: Use `mode: 'onBlur'` in useForm to validate on blur for better UX:

```tsx
const methods = useForm({
  resolver: zodResolver(schema),
  mode: 'onBlur'
});
```

## Accessibility

* Inherits all accessibility features from [DateInput](/docs/date-input) component
* Proper ARIA attributes for error states
* Keyboard navigable
* Screen reader compatible

## Related Components

* [DateInput](/docs/date-input) - Base date input component
* [RHFInputGroup](/docs/rhf-input-group) - Input group wrapper with label and error
* [RHFError](/docs/rhf-error) - Error message display

# RHFDateRangeInput

import { RHFDateRangeInput } from '@geckoui/geckoui';
import { BasicRHFDateRangeInputExample, WithValidationExample, WithDefaultValueExample, NumberOfMonthsExample, CompleteFormExample } from '@/components/examples/rhf-date-range-input-examples';

# RHFDateRangeInput

A date range input component integrated with React Hook Form. Automatically displays error states when validation fails and supports all DateRangeInput features.

## Installation

```tsx
import { RHFDateRangeInput } from '@geckoui/geckoui';
```

## Basic Usage

```tsx
import { useForm, FormProvider } from 'react-hook-form';
import { RHFDateRangeInput } from '@geckoui/geckoui';
import type { DateRange } from '@geckoui/geckoui';

function Example() {
  const methods = useForm({
    defaultValues: {
      dateRange: undefined as DateRange | undefined
    }
  });

return (
    <FormProvider {...methods}>
      <RHFDateRangeInput name="dateRange" />
    </FormProvider>
  );
}
```

## Props API

Extends all props from [DateRangeInput](/docs/date-range-input) component plus:

| Prop             | Type                                           | Default        | Description                                  |
| ---------------- | ---------------------------------------------- | -------------- | -------------------------------------------- |
| `name`           | `string`                                       | -              | Field name (required)                        |
| `control`        | `Control`                                      | Auto-injected  | Optional: Pass explicitly for nested forms   |
| `rules`          | `RegisterOptions`                              | -              | Inline validation rules                      |
| `onChange`       | `(value: DateRange \| null) => void`           | -              | Change callback (in addition to form update) |
| `disabled`       | `boolean`                                      | `false`        | Disable the input                            |
| `format`         | `'DD/MM/YYYY' \| 'MM/DD/YYYY' \| 'YYYY/MM/DD'` | `'DD/MM/YYYY'` | Date display format                          |
| `numberOfMonths` | `1 \| 2`                                       | `2`            | Number of months in calendar                 |
| ...rest          | `DateRangeInputProps`                          | -              | All DateRangeInput props                     |

## Examples

### With Validation (Zod)

```tsx
import { useForm, FormProvider } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';
import { RHFDateRangeInput, RHFInputGroup, Button } from '@geckoui/geckoui';

const schema = z.object({
  dateRange: z
    .object({
      from: z.string().nullable(),
      to: z.string().nullable().optional()
    })
    .refine((data) => data.from && data.to, {
      message: 'Please select both start and end dates'
    })
});

function Example() {
  const methods = useForm({
    resolver: zodResolver(schema),
    mode: 'onBlur',
    defaultValues: {
      dateRange: { from: null, to: null }
    }
  });

return (
    <FormProvider {...methods}>
      <RHFInputGroup label="Date Range" required>
        <RHFDateRangeInput name="dateRange" />
      </RHFInputGroup>
    </FormProvider>
  );
}
```

### With Default Value

```tsx
const methods = useForm({
  defaultValues: {
    dateRange: {
      from: '2024-06-01',
      to: '2024-06-15'
    }
  }
});

<RHFDateRangeInput name="dateRange" />
```

### Single Month Display

```tsx
<RHFDateRangeInput name="dateRange" numberOfMonths={1} />
```

### Complete Form

```tsx
const schema = z.object({
  eventName: z.string().min(1, 'Event name is required'),
  dateRange: z
    .object({
      from: z.string().nullable(),
      to: z.string().nullable().optional()
    })
    .refine((data) => data.from, {
      message: 'Start date is required'
    })
});

const methods = useForm({
  resolver: zodResolver(schema),
  defaultValues: {
    eventName: '',
    dateRange: { from: null, to: null }
  }
});

<form onSubmit={methods.handleSubmit(onSubmit)}>
  <RHFInputGroup label="Event Name" required>
    <RHFInput name="eventName" placeholder="Enter event name" />
  </RHFInputGroup>
  <RHFInputGroup label="Event Dates" required>
    <RHFDateRangeInput name="dateRange" />
  </RHFInputGroup>
  <Button type="submit">Create Event</Button>
</form>
```

## Inline Rules Validation

For simple validation, use the `rules` prop:

```tsx
<RHFDateRangeInput
  name="dateRange"
  rules={{ required: 'Please select a date range' }}
/>
```

For complex forms, we recommend using a schema resolver (Zod, Yup) instead.

## Error States

The component automatically shows a red border when validation fails:

* **Required validation**: When the field is required but empty
* **Custom validation**: When custom Zod refinements fail
* **Range validation**: When validating that both dates are selected

Error messages can be displayed using the [RHFError](/docs/rhf-error) component or [RHFInputGroup](/docs/rhf-input-group).

## Related Components

* [DateRangeInput](/docs/date-range-input) - Base date range input component
* [RHFDateInput](/docs/rhf-date-input) - Single date input with RHF
* [RHFInputGroup](/docs/rhf-input-group) - Form field wrapper with label and error
* [RHFError](/docs/rhf-error) - Error message display

# RHFError

import { RHFError } from '@geckoui/geckoui';
import {
  BasicRHFErrorExample,
  WithCustomStylingExample,
  WithCustomRenderExample,
  MultipleFieldsExample,
  WithIconExample,
  WithControlPropExample,
  CompleteFormErrorExample
} from '@/components/examples/rhf-error-examples';

# RHFError

A component for displaying form field error messages with React Hook Form. Automatically shows validation error messages for the specified field. Supports custom rendering and styling of error messages.

## Installation

```tsx
import { RHFError } from '@geckoui/geckoui';
```

## Basic Usage

```tsx
import { useForm, FormProvider } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';
import { RHFInput, RHFError } from '@geckoui/geckoui';

const schema = z.object({
  errorUsername: z.string().min(3, 'Username must be at least 3 characters')
});

function Example() {
  const methods = useForm({
    resolver: zodResolver(schema),
    mode: 'onBlur',
    defaultValues: { errorUsername: '' }
  });

return (
    <FormProvider {...methods}>
      <div className="space-y-2">
        <RHFInput name="errorUsername" placeholder="Enter username and blur to see error" />
        <RHFError name="errorUsername" />
      </div>
    </FormProvider>
  );
}
```

## Props API

| Prop        | Type       | Default       | Description                                                       |
| ----------- | ---------- | ------------- | ----------------------------------------------------------------- |
| `name`      | `string`   | -             | Field name to display errors for (required)                       |
| `control`   | `Control`  | Auto-injected | Optional: Pass explicitly for nested forms or custom form context |
| `className` | `string`   | -             | Class name for error message (only when `render` is not provided) |
| `render`    | `Function` | -             | Custom error rendering function                                   |

## Examples

### With Custom Styling

```tsx
<RHFInput name="styledEmail" placeholder="Enter email" />
<RHFError name="styledEmail" className="font-bold text-red-700 text-lg" />
```

### With Custom Render Function

```tsx
const schema = z.object({
  renderPassword: z.string().min(8, 'Password must be at least 8 characters')
});

<RHFInput name="renderPassword" type="password" placeholder="Enter password" />
<RHFError
  name="renderPassword"
  render={({ error }) => {
    if (!error) return null;
    return (
      <div className="flex items-center space-x-2 bg-red-50 p-2 rounded">
        <span className="text-red-500 text-xl">⚠️</span>
        <span className="text-sm font-medium text-red-600">
          {error?.message}
        </span>
      </div>
    );
  }}
/>
```

### Multiple Fields with Errors

```tsx
const schema = z.object({
  multiUsername: z.string().min(3, 'Username must be at least 3 characters'),
  multiEmail: z.string().email('Invalid email address'),
  multiPassword: z.string().min(8, 'Password must be at least 8 characters')
});

<div className="space-y-4">
  <div className="space-y-1">
    <label className="text-sm font-medium">Username</label>
    <RHFInput name="multiUsername" placeholder="Enter username" />
    <RHFError name="multiUsername" />
  </div>

<div className="space-y-1">
    <label className="text-sm font-medium">Email</label>
    <RHFInput name="multiEmail" type="email" placeholder="Enter email" />
    <RHFError name="multiEmail" />
  </div>

<div className="space-y-1">
    <label className="text-sm font-medium">Password</label>
    <RHFInput name="multiPassword" type="password" placeholder="Enter password" />
    <RHFError name="multiPassword" />
  </div>
</div>
```

### With Icon

```tsx
<RHFInput name="iconEmail" placeholder="Enter email" />
<RHFError
  name="iconEmail"
  render={({ error }) => {
    if (!error) return null;
    return (
      <div className="flex items-center space-x-2">
        <svg className="h-5 w-5 text-red-500" fill="currentColor" viewBox="0 0 20 20">
          <path fillRule="evenodd" d="M18 10a8 8 0 11-16 0 8 8 0 0116 0zm-7 4a1 1 0 11-2 0 1 1 0 012 0zm-1-9a1 1 0 00-1 1v4a1 1 0 102 0V6a1 1 0 00-1-1z" clipRule="evenodd" />
        </svg>
        <span className="text-sm text-red-600">{error?.message}</span>
      </div>
    );
  }}
/>
```

### With Explicit Control Prop

```tsx
const methods = useForm({
  resolver: zodResolver(schema),
  mode: 'onBlur'
});

<RHFInput name="controlField" placeholder="Enter text" />
<RHFError name="controlField" control={methods.control} />
```

### Complete Form Example

```tsx
import { useForm, FormProvider } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';
import { RHFInput, RHFError, Button } from '@geckoui/geckoui';

const schema = z.object({
  formErrorUsername: z.string().min(3, 'Username must be at least 3 characters'),
  formErrorEmail: z.string().email('Invalid email address'),
  formErrorPassword: z.string()
    .min(8, 'Password must be at least 8 characters')
    .regex(/[0-9]/, 'Password must contain at least one number'),
  formErrorConfirm: z.string()
}).refine((data) => data.formErrorPassword === data.formErrorConfirm, {
  message: "Passwords don't match",
  path: ['formErrorConfirm']
});

function RegistrationForm() {
  const methods = useForm({
    resolver: zodResolver(schema),
    mode: 'onBlur',
    defaultValues: {
      formErrorUsername: '',
      formErrorEmail: '',
      formErrorPassword: '',
      formErrorConfirm: ''
    }
  });

const onSubmit = (data: any) => {
    console.log('Form data:', data);
    alert('Form submitted! Check console for data.');
  };

return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit(onSubmit)} className="space-y-4">
        <div className="space-y-1">
          <label className="text-sm font-medium">Username *</label>
          <RHFInput name="formErrorUsername" placeholder="Enter username" />
          <RHFError name="formErrorUsername" />
        </div>

<div className="space-y-1">
          <label className="text-sm font-medium">Email *</label>
          <RHFInput name="formErrorEmail" type="email" placeholder="Enter email" />
          <RHFError name="formErrorEmail" />
        </div>

<div className="space-y-1">
          <label className="text-sm font-medium">Password *</label>
          <RHFInput name="formErrorPassword" type="password" placeholder="Enter password" />
          <RHFError name="formErrorPassword" />
        </div>

<div className="space-y-1">
          <label className="text-sm font-medium">Confirm Password *</label>
          <RHFInput name="formErrorConfirm" type="password" placeholder="Confirm password" />
          <RHFError name="formErrorConfirm" />
        </div>

<Button type="submit">
          Submit
        </Button>
      </form>
    </FormProvider>
  );
}
```

## How It Works

RHFError uses React Hook Form's `Controller` component internally to:

1. **Access field state** - Gets the `fieldState` for the specified field name
2. **Check for errors** - Returns `null` (no render) if no error exists
3. **Display error message** - Shows `error.message` in an `InputError` component
4. **Support custom rendering** - Allows complete control via the `render` prop

The component only renders when there's an error, making it efficient and clean.

## Render Prop API

The `render` prop receives a `ControllerFieldState` object with:

```tsx
{
  error?: {
    message?: string;
    type?: string;
  };
  invalid: boolean;
  isDirty: boolean;
  isTouched: boolean;
}
```

Example usage:

```tsx
<RHFError
  name="email"
  render={({ error, invalid, isTouched }) => {
    if (!error) return null;

return (
      <div className={`error ${isTouched ? 'touched' : ''}`}>
        {error.message}
      </div>
    );
  }}
/>
```

## Usage Patterns

### With RHFInputGroup

The easiest way to use RHFError is through [RHFInputGroup](/docs/rhf-input-group), which automatically includes it:

```tsx
<RHFInputGroup label="Email" required>
  <RHFInput name="email" />
</RHFInputGroup>
```

### Manual Layout

For custom layouts, use RHFError manually:

```tsx
<div className="field-container">
  <Label htmlFor="email">Email Address</Label>
  <RHFInput id="email" name="email" />
  <RHFError name="email" />
</div>
```

### Multiple Errors

For fields with multiple validation rules, Zod returns the first error encountered:

```tsx
const schema = z.object({
  password: z.string()
    .min(8, 'Minimum 8 characters')
    .regex(/[A-Z]/, 'Must contain uppercase')
    .regex(/[0-9]/, 'Must contain number')
});

<RHFError name="password" />
```

## Best Practices

1. **Validation mode** - Use `mode: 'onBlur'` for better UX:
   ```tsx
   const methods = useForm({
     resolver: zodResolver(schema),
     mode: 'onBlur' // Shows errors after user leaves field
   });
   ```

2. **Error messages** - Write clear, actionable error messages:
   ```tsx
   z.string().min(8, 'Password must be at least 8 characters')
   // ✅ Clear and actionable

z.string().min(8, 'Invalid')
   // ❌ Too vague
   ```

3. **Consistent styling** - Use `className` for simple styling, `render` for complex designs:
   ```tsx
   <RHFError name="email" className="text-sm text-red-600" />
   ```

4. **Accessibility** - Error messages are automatically associated with inputs when using RHFInputGroup

## Accessibility

* Error messages are rendered in a `<p>` tag with proper ARIA attributes via the `InputError` component
* Errors are announced to screen readers when they appear
* The `GeckoUIRHFError` CSS class is applied for custom styling
* Works seamlessly with keyboard navigation

## Related Components

* [RHFInputGroup](/docs/rhf-input-group) - Layout component that includes RHFError
* [RHFInput](/docs/rhf-input) - Text input with React Hook Form
* [RHFTextarea](/docs/rhf-textarea) - Multi-line text input
* [InputError](/docs/input-error) - Base error message component

# RHFFileInput

import { RHFFileInput } from '@geckoui/geckoui';
import {
  BasicRHFFileInputExample,
  WithValidationExample,
  MultipleFilesExample,
  AcceptTypesExample,
  CustomRenderExample,
  WithCallbackExample,
  CompleteFormExample
} from '@/components/examples/rhf-file-input-examples';

# RHFFileInput

A file input component integrated with React Hook Form that automatically creates preview URLs for selected files. Supports single and multiple file selection with custom rendering capabilities.

## Installation

```tsx
import { RHFFileInput } from '@geckoui/geckoui';
```

## Basic Usage

```tsx
import { useForm, FormProvider } from 'react-hook-form';
import { RHFFileInput } from '@geckoui/geckoui';

function Example() {
  const methods = useForm({
    defaultValues: {
      basicFile: undefined
    }
  });

return (
    <FormProvider {...methods}>
      <RHFFileInput name="basicFile" />
    </FormProvider>
  );
}
```

## Props API

Extends all props from standard HTML `<input type="file">` element plus:

| Prop             | Type                    | Default       | Description                                                       |
| ---------------- | ----------------------- | ------------- | ----------------------------------------------------------------- |
| `name`           | `string`                | -             | Field name (required)                                             |
| `control`        | `Control`               | Auto-injected | Optional: Pass explicitly for nested forms or custom form context |
| `rules`          | `RegisterOptions`       | -             | Inline validation rules                                           |
| `multiple`       | `boolean`               | `false`       | Allow multiple file selection                                     |
| `accept`         | `string`                | -             | File types to accept (e.g., "image/\*", ".pdf")                   |
| `onChange`       | `(data) => void`        | -             | Change callback (receives file data, not event)                   |
| `onBlur`         | `(event) => void`       | -             | Blur callback                                                     |
| `render`         | `ReactNode \| Function` | -             | Custom render function with access to controller props            |
| `className`      | `string`                | -             | Class for wrapper element                                         |
| `inputClassName` | `string`                | -             | Class for input element itself                                    |
| `disabled`       | `boolean`               | `false`       | Disable file input                                                |
| ...rest          | `InputHTMLAttributes`   | -             | All other input attributes                                        |

## Examples

### With Validation (Zod)

```tsx
import { useForm, FormProvider } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';
import { RHFFileInput, RHFInputGroup, Button } from '@geckoui/geckoui';

const schema = z.object({
  validationAvatar: z
    .instanceof(File, { message: 'Please select a file' })
    .refine((file) => file.size <= 5000000, 'File size must be less than 5MB')
    .refine(
      (file) => ['image/jpeg', 'image/png', 'image/webp'].includes(file.type),
      'Only JPEG, PNG, and WebP images are allowed'
    )
});

function Example() {
  const methods = useForm({
    resolver: zodResolver(schema),
    mode: 'onBlur',
    defaultValues: {
      validationAvatar: undefined
    }
  });

return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit(console.log)}>
        <RHFInputGroup label="Profile Picture" required>
          <RHFFileInput name="validationAvatar" accept="image/*" />
        </RHFInputGroup>
        <Button type="submit">Upload</Button>
      </form>
    </FormProvider>
  );
}
```

### Multiple Files

```tsx
<RHFFileInput name="multipleImages" multiple accept="image/*" />
```

### Restrict File Types

```tsx
<RHFFileInput name="pdfDocument" accept=".pdf" />
```

### Custom Render with Preview

```tsx
<RHFFileInput
  name="customAvatar"
  accept="image/*"
  render={({ field: { value } }) => {
    return (
      <div className="flex rounded overflow-hidden items-center justify-center cursor-pointer border-2 p-4 w-full border-dotted border-gray-300 h-[200px]">
        {value ? (
          <img
            className="inline-block object-contain w-full h-full"
            src={value.preview}
            alt="Preview"
          />
        ) : (
          <span>Click to Upload Image</span>
        )}
      </div>
    );
  }}
/>
```

### With onChange Callback

```tsx
const handleFileChange = (data: FileWithPreview | FileWithPreview[]) => {
  console.log('File selected:', data);
  if (data && !Array.isArray(data)) {
    alert(`File selected: ${data.name} (${(data.size / 1024).toFixed(2)} KB)`);
  }
};

<RHFFileInput name="callbackFile" onChange={handleFileChange} />
```

### Complete Form Example

const schema = z.object({
  resume: z
    .instanceof(File, { message: 'Resume is required' })
    .refine((file) => file.size <= 10000000, 'File size must be less than 10MB')
    .refine(
      (file) => ['application/pdf', 'application/msword', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'].includes(file.type),
      'Only PDF and Word documents are allowed'
    ),
  portfolio: z
    .array(z.instanceof(File))
    .min(1, 'At least one portfolio item is required')
    .max(5, 'Maximum 5 files allowed')
    .refine(
      (files) => files.every((file) => file.size <= 5000000),
      'Each file must be less than 5MB'
    )
    .refine(
      (files) => files.every((file) => ['image/jpeg', 'image/png', 'image/webp'].includes(file.type)),
      'Only JPEG, PNG, and WebP images are allowed'
    )
});

function ApplicationForm() {
  const methods = useForm({
    resolver: zodResolver(schema),
    mode: 'onBlur',
    defaultValues: {
      resume: undefined,
      portfolio: undefined
    }
  });

return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit(console.log)}>
        <RHFInputGroup label="Resume" required>
          <RHFFileInput name="resume" accept=".pdf,.doc,.docx" />
        </RHFInputGroup>

<Button type="submit">Submit Application</Button>
      </form>
    </FormProvider>
  );
}
```

## Inline Rules Validation

For simple validation, use the `rules` prop:

```tsx
<RHFFileInput
  name="avatar"
  rules={{ required: 'Please upload a file' }}
/>
```

For complex forms, we recommend using a schema resolver (Zod, Yup) instead.

## File Preview

RHFFileInput automatically creates preview URLs for selected files:

* Each file has a `preview` property containing an Object URL
* For single files: `value.preview`
* For multiple files: `value.map(file => file.preview)`
* Perfect for displaying image previews before upload

```tsx
<RHFFileInput
  name="image"
  render={({ field: { value } }) => (
    value && <img src={value.preview} alt="Preview" />
  )}
/>
```

## File Types

The `accept` prop accepts standard HTML file input values:

```tsx
accept="image/*"
accept=".pdf"
accept=".jpg,.jpeg,.png"
accept="video/*"
accept=".doc,.docx,application/pdf"
```

Common MIME types:

* Images: `image/*`, `image/jpeg`, `image/png`, `image/webp`
* Documents: `application/pdf`, `application/msword`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document`
* Videos: `video/*`, `video/mp4`

## Validation with Zod

For single file:

```tsx
z.instanceof(File, { message: 'File is required' })
  .refine((file) => file.size <= 5000000, 'Max file size is 5MB')
  .refine(
    (file) => ['image/jpeg', 'image/png'].includes(file.type),
    'Only JPEG and PNG allowed'
  )
```

For multiple files:

```tsx
z.array(z.instanceof(File))
  .min(1, 'At least one file required')
  .max(5, 'Maximum 5 files')
  .refine(
    (files) => files.every((file) => file.size <= 5000000),
    'Each file must be less than 5MB'
  )
```

## Error States

RHFFileInput automatically displays error states with:

* Red border via `GeckoUIRHFFileInput--error` CSS class when validation fails
* Use with [RHFInputGroup](/docs/rhf-input-group) for label + error message display

```tsx
<RHFInputGroup label="Upload File" required>
  <RHFFileInput name="file" />
</RHFInputGroup>
```

**Tip**: Use `mode: 'onBlur'` in useForm to validate after file selection:

```tsx
const methods = useForm({
  resolver: zodResolver(schema),
  mode: 'onBlur'
});
```

## Custom Rendering

The `render` prop provides full control over the UI while maintaining form integration:

```tsx
<RHFFileInput
  name="file"
  render={({ field, fieldState, formState }) => (
    <div>
      {field.value && <p>{field.value.name}</p>}
      {fieldState.error && <p>{fieldState.error.message}</p>}
    </div>
  )}
/>
```

When using `render`, the default input is hidden but still functional.

## Accessibility

* Standard HTML file input accessibility
* Keyboard navigable (Tab to focus, Enter/Space to open)
* Screen reader compatible
* Proper ARIA attributes for error states

## Related Components

* [RHFFilePicker](/docs/rhf-file-picker) - Drag-and-drop file picker with directory support
* [RHFInputGroup](/docs/rhf-input-group) - Label + input + error wrapper
* [RHFError](/docs/rhf-error) - Error message display

# RHFFilePicker

import { RHFFilePicker } from '@geckoui/geckoui';
import {
  BasicRHFFilePickerExample,
  WithValidationExample,
  RemoveDuplicatesExample,
  KeepOldFilesExample,
  CustomRenderExample,
  WithCallbacksExample,
  CompleteFormExample
} from '@/components/examples/rhf-file-picker-examples';

# RHFFilePicker

An advanced file picker component with drag-and-drop support, directory selection, and duplicate detection integrated with React Hook Form. Perfect for uploading multiple files or entire directories.

## Installation

```tsx
import { RHFFilePicker } from '@geckoui/geckoui';
```

## Basic Usage

```tsx
import { useForm, FormProvider } from 'react-hook-form';
import { RHFFilePicker } from '@geckoui/geckoui';

function Example() {
  const methods = useForm({
    defaultValues: {
      basicFiles: []
    }
  });

return (
    <FormProvider {...methods}>
      <RHFFilePicker name="basicFiles" />
    </FormProvider>
  );
}
```

## Props API

| Prop               | Type                        | Default       | Description                                                                |
| ------------------ | --------------------------- | ------------- | -------------------------------------------------------------------------- |
| `name`             | `string`                    | -             | Field name (required)                                                      |
| `control`          | `Control`                   | Auto-injected | Optional: Pass explicitly for nested forms or custom form context          |
| `rules`            | `RegisterOptions`           | -             | Inline validation rules                                                    |
| `accept`           | `string`                    | `*`           | File types to accept (e.g., "image/\*", ".pdf")                            |
| `keepOldFiles`     | `boolean`                   | `false`       | Keep previously selected files when adding new ones                        |
| `removeDuplicates` | `boolean`                   | `false`       | Automatically remove duplicate files(Only works if `keepOldFiles` is true) |
| `transform`        | `(files) => files`          | -             | Transform files before setting them                                        |
| `onChange`         | `(files, newFiles) => void` | -             | Callback when files change                                                 |
| `onError`          | `(error) => void`           | -             | Callback when an error occurs                                              |
| `render`           | `Function`                  | -             | Custom render function with access to picker state                         |

## Examples

### With Validation (Zod)

```tsx
import { useForm, FormProvider } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';
import { RHFFilePicker, RHFInputGroup, Button } from '@geckoui/geckoui';

const schema = z.object({
  validationImages: z
    .array(z.custom<File>())
    .min(1, 'At least one image is required')
    .max(10, 'Maximum 10 images allowed')
    .refine(
      (files) => files.every((file) => file.size <= 5000000),
      'Each file must be less than 5MB'
    )
    .refine(
      (files) => files.every((file) => ['image/jpeg', 'image/png', 'image/webp'].includes(file.type)),
      'Only JPEG, PNG, and WebP images are allowed'
    )
});

function Example() {
  const methods = useForm({
    resolver: zodResolver(schema),
    mode: 'onBlur',
    defaultValues: {
      validationImages: []
    }
  });

return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit(console.log)}>
        <RHFInputGroup label="Product Images" required>
          <RHFFilePicker name="validationImages" accept="image/*" />
        </RHFInputGroup>
        <Button type="submit">Upload Images</Button>
      </form>
    </FormProvider>
  );
}
```

### Keep Old Files

Accumulate files across multiple selections:

```tsx
<RHFFilePicker name="accumulatedFiles" keepOldFiles />
```

### Remove Duplicates

If you set `keepOldFiles`, you can also enable `removeDuplicates` to avoid duplicate files:
So, if a user selects the same file multiple times, only one instance will be kept.

```tsx
<RHFFilePicker name="uniqueDocuments" keepOldFiles removeDuplicates />
```

### Custom Render with Image Grid

```tsx
<RHFFilePicker
  name="customImages"
  accept="image/*"
  render={({
    dropzoneRef,
    dragging,
    loading,
    field: { value: files, onChange },
    openFilePicker,
  }) => {
    const handleRemove = (preview: string) => {
      onChange(files.filter((f) => f.preview !== preview));
    };

return (
      <div className="flex flex-col gap-3">
        {/* Compact upload area */}
        <div
          ref={dropzoneRef}
          onClick={() => openFilePicker()}
          className={`relative flex cursor-pointer items-center justify-center rounded-lg border-2 border-dashed p-4 transition-colors ${
            dragging ? 'border-primary-400 bg-primary-50' : 'border-gray-300 hover:border-primary-300'
          }`}
        >
          <div className="flex items-center gap-3 text-sm text-gray-500">
            <UploadIcon className="h-5 w-5" />
            <span>{dragging ? 'Drop images here' : 'Click to upload or drag and drop'}</span>
          </div>
          {loading && (
            <div className="absolute inset-0 flex items-center justify-center rounded-lg bg-white/50">
              <Spinner className="h-5 w-5" />
            </div>
          )}
        </div>

{/* Image grid */}
        {!!files?.length && (
          <div className="grid grid-cols-4 gap-2 sm:grid-cols-5 md:grid-cols-6">
            {files.map((file) => (
              <div key={file.preview} className="group relative aspect-square">
                <img
                  src={file.preview}
                  alt={file.name}
                  className="h-full w-full rounded-lg border object-cover"
                />
                <button
                  type="button"
                  onClick={() => handleRemove(file.preview)}
                  className="absolute -right-1.5 -top-1.5 flex h-5 w-5 items-center justify-center rounded-full bg-red-500 text-white opacity-0 shadow-sm hover:bg-red-600 group-hover:opacity-100"
                >
                  <XIcon className="h-3 w-3" />
                </button>
              </div>
            ))}
          </div>
        )}
      </div>
    );
  }}
/>
```

### With Callbacks

```tsx
const handleChange = (files: FilePickerFile[], newFiles: FilePickerFile[]) => {
  console.log('All files:', files);
  console.log('New files:', newFiles);
};

const handleError = (error: Error) => {
  console.error('File picker error:', error);
  alert(`Error: ${error.message}`);
};

<RHFFilePicker
  name="callbackFiles"
  onChange={handleChange}
  onError={handleError}
/>
```

### Complete Form Example

const schema = z.object({
  projectFiles: z
    .array(z.custom<File>())
    .min(1, 'At least one file is required')
    .refine(
      (files) => files.every((file) => file.size <= 10000000),
      'Each file must be less than 10MB'
    ),
  screenshots: z
    .array(z.custom<File>())
    .min(3, 'At least 3 screenshots are required')
    .max(10, 'Maximum 10 screenshots allowed')
    .refine(
      (files) => files.every((file) => ['image/jpeg', 'image/png', 'image/webp'].includes(file.type)),
      'Only JPEG, PNG, and WebP images are allowed'
    )
});

function ProjectForm() {
  const methods = useForm({
    resolver: zodResolver(schema),
    mode: 'onBlur',
    defaultValues: {
      projectFiles: [],
      screenshots: []
    }
  });

return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit(console.log)}>
        <RHFInputGroup label="Project Files" required>
          <RHFFilePicker name="projectFiles" />
        </RHFInputGroup>

<Button type="submit">Submit Project</Button>
      </form>
    </FormProvider>
  );
}
```

## Inline Rules Validation

For simple validation, use the `rules` prop:

```tsx
<RHFFilePicker
  name="files"
  rules={{ required: 'Please upload at least one file' }}
/>
```

For complex forms, we recommend using a schema resolver (Zod, Yup) instead.

## File Properties

Each file in the picker has these properties:

```typescript
interface FilePickerFile extends File {
  preview: string;
  path: string;
  editableName: string;
}
```

* `preview`: Object URL for displaying file content
* `path`: File system path (from directory picker or webkitRelativePath)
* `editableName`: Editable name property (since File.name is read-only)

## Drag and Drop

RHFFilePicker automatically handles drag-and-drop:

1. Drag files over the dropzone
2. The `dragging` state becomes `true`
3. Drop files to add them
4. Files are processed and previews are created

Access drag state in custom render:

```tsx
render={({ dragging, dropzoneRef }) => (
  <div
    ref={dropzoneRef}
    className={dragging ? 'border-blue-400' : 'border-gray-300'}
  >
    Drop files here
  </div>
)}
```

## Directory Selection

Select entire directories using the `openFilePicker` function:

```tsx
render={({ openFilePicker }) => (
  <Button onClick={() => openFilePicker({ directory: true })}>
    Select Directory
  </Button>
)}
```

This preserves the directory structure in the `path` property of each file.

## Duplicate Detection

When `removeDuplicates={true}`:

* Files with identical names and sizes are considered duplicates
* Only the first occurrence is kept
* Duplicates are automatically filtered out

Files also have a `duplicatedWith` property containing an array of files they duplicate.

## File Transformation

Transform files before they're set in the form:

```tsx
const transform = async (files: FilePickerFile[]) => {
  return files.map(file => {
    file.editableName = file.name.toLowerCase();
    return file;
  });
};

<RHFFilePicker name="files" transform={transform} />
```

## File Types

The `accept` prop accepts standard file input values:

```tsx
accept="image/*"
accept=".pdf"
accept=".jpg,.jpeg,.png"
accept="video/*"
accept=".doc,.docx,application/pdf"
```

## Validation with Zod

Validate file arrays with Zod:

```tsx
z.array(z.custom<File>())
  .min(1, 'At least one file required')
  .max(10, 'Maximum 10 files')
  .refine(
    (files) => files.every((file) => file.size <= 5000000),
    'Each file must be less than 5MB'
  )
  .refine(
    (files) => files.every((file) =>
      ['image/jpeg', 'image/png'].includes(file.type)
    ),
    'Only JPEG and PNG allowed'
  )
```

## Error States

RHFFilePicker automatically displays error states:

* Red border via `GeckoUIRHFFilePicker--error` CSS class when validation fails
* Use with [RHFInputGroup](/docs/rhf-input-group) for complete error display

```tsx
<RHFInputGroup label="Upload Files" required>
  <RHFFilePicker name="files" />
</RHFInputGroup>
```

**Tip**: Use `mode: 'onBlur'` to validate after file selection:

```tsx
const methods = useForm({
  resolver: zodResolver(schema),
  mode: 'onBlur'
});
```

## Loading States

The picker automatically manages loading states:

```tsx
render={({ loading }) => (
  loading ? <Spinner /> : <div>Ready to upload</div>
)}
```

Loading occurs during:

* File processing
* Preview URL generation
* Transform function execution

## Custom Rendering

The `render` prop provides access to picker state:

```tsx
render={({
  dropzoneRef,
  dragging,
  loading,
  openFilePicker,
  files,
  field,
  fieldState,
  formState
}) => (
  <div ref={dropzoneRef}>
    {/* Custom UI */}
  </div>
)}
```

**Important**: Always attach `dropzoneRef` to your dropzone element for drag-and-drop to work.

## Accessibility

* Keyboard navigable buttons
* Screen reader compatible
* Proper ARIA attributes for loading and error states
* Focus management for file picker dialogs

## Performance Tips

1. Use `removeDuplicates` to prevent duplicate uploads
2. Set file size limits in validation
3. Limit file count with Zod `.max()`
4. Use `accept` to restrict file types before selection

## Related Components

* [RHFFileInput](/docs/rhf-file-input) - Simple file input for single/multiple files
* [RHFInputGroup](/docs/rhf-input-group) - Label + input + error wrapper
* [RHFError](/docs/rhf-error) - Error message display

# RHFInputGroup

import { RHFInputGroup } from '@geckoui/geckoui';
import {
  BasicRHFInputGroupExample,
  WithRequiredExample,
  WithHelpTextExample,
  WithTextareaExample,
  WithNestedStructureExample,
  WithCustomStylingExample,
  CompleteFormGroupExample
} from '@/components/examples/rhf-input-group-examples';

# RHFInputGroup

A layout convenience component that combines a form field label, input component, and error message into a cohesive unit. Automatically detects RHF input components in children (even nested) and extracts their name and control to display validation errors. Reduces boilerplate for standard form field layouts.

> **Recommended Pattern**: Use `RHFInputGroup` when you need label and input detection. It automatically handles the label-input association and error display, reducing boilerplate.

## Installation

```tsx
import { RHFInputGroup } from '@geckoui/geckoui';
```

## Basic Usage

```tsx
import { useForm, FormProvider } from 'react-hook-form';
import { RHFInput, RHFInputGroup } from '@geckoui/geckoui';

function Example() {
  const methods = useForm({
    defaultValues: {
      basicUsername: ''
    }
  });

return (
    <FormProvider {...methods}>
      <RHFInputGroup label="Username">
        <RHFInput name="basicUsername" placeholder="Enter username" />
      </RHFInputGroup>
    </FormProvider>
  );
}
```

## Props API

Extends all props from [Label](/docs/label) component plus:

| Prop             | Type         | Default | Description                           |
| ---------------- | ------------ | ------- | ------------------------------------- |
| `label`          | `string`     | -       | Label text for the input group        |
| `labelClassName` | `string`     | -       | Class name for the label element      |
| `className`      | `string`     | -       | Class name for the wrapper div        |
| `errorClassName` | `string`     | -       | Class name for the error message      |
| `children`       | `ReactNode`  | -       | Input component(s) to wrap (required) |
| `required`       | `boolean`    | -       | Shows required asterisk (\*) on label |
| `tooltip`        | `string`     | -       | Tooltip text shown on label hover     |
| ...rest          | `LabelProps` | -       | All Label component props             |

## Examples

### With Required Field

```tsx
import { useForm, FormProvider } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';
import { RHFInput, RHFInputGroup } from '@geckoui/geckoui';

const schema = z.object({
  groupEmail: z.string().email('Invalid email address').min(1, 'Email is required')
});

function Example() {
  const methods = useForm({
    resolver: zodResolver(schema),
    mode: 'onBlur',
    defaultValues: { groupEmail: '' }
  });

return (
    <FormProvider {...methods}>
      <RHFInputGroup label="Email Address" required>
        <RHFInput name="groupEmail" type="email" placeholder="Enter email and blur to see validation" />
      </RHFInputGroup>
    </FormProvider>
  );
}
```

### With Help Text (Tooltip)

```tsx
<RHFInputGroup
  label="Password"
  required
  tooltip="Must be at least 8 characters with numbers and special characters"
>
  <RHFInput name="tooltipPassword" type="password" placeholder="Enter password" />
</RHFInputGroup>
```

### With Textarea

```tsx
import { RHFTextarea } from '@geckoui/geckoui';

const schema = z.object({
  groupBio: z.string().min(10, 'Bio must be at least 10 characters').max(200, 'Bio must be less than 200 characters')
});

<RHFInputGroup label="Bio" required tooltip="Tell us about yourself">
  <RHFTextarea
    name="groupBio"
    placeholder="Write your bio here..."
    rows={4}
  />
</RHFInputGroup>
```

### With Nested Structure

The component automatically finds the first RHF input component even when nested:

```tsx
const schema = z.object({
  nestedPassword: z.string()
    .min(8, 'Password must be at least 8 characters')
    .regex(/[0-9]/, 'Password must contain at least one number')
    .regex(/[!@#$%^&*]/, 'Password must contain at least one special character')
});

<RHFInputGroup
  label="Password"
  required
  tooltip="Must meet all requirements below"
>
  <div className="space-y-2">
    <RHFInput name="nestedPassword" type="password" placeholder="Enter password" />
    <ul className="text-sm text-gray-600 space-y-1">
      <li>✓ At least 8 characters</li>
      <li>✓ Include a number</li>
      <li>✓ Include a special character</li>
    </ul>
  </div>
</RHFInputGroup>
```

### With Custom Styling

```tsx
<RHFInputGroup
  label="Custom Styled Input"
  labelClassName="text-blue-600 font-semibold"
  className="bg-blue-50 p-4 rounded-lg"
  errorClassName="text-blue-800 font-bold"
>
  <RHFInput name="styledInput" placeholder="This has custom styling" />
</RHFInputGroup>
```

### Complete Form Example

```tsx
import { useForm, FormProvider } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';
import { RHFInput, RHFTextarea, RHFInputGroup, Button } from '@geckoui/geckoui';

const schema = z.object({
  formUsername: z.string().min(3, 'Username must be at least 3 characters'),
  formEmail: z.string().email('Invalid email address'),
  formBio: z.string().min(10, 'Bio must be at least 10 characters'),
  formPassword: z.string().min(8, 'Password must be at least 8 characters')
});

function RegistrationForm() {
  const methods = useForm({
    resolver: zodResolver(schema),
    mode: 'onBlur',
    defaultValues: {
      formUsername: '',
      formEmail: '',
      formBio: '',
      formPassword: ''
    }
  });

const onSubmit = (data: any) => {
    console.log('Form data:', data);
    alert('Form submitted! Check console for data.');
  };

return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit(onSubmit)} className="space-y-4">
        <RHFInputGroup label="Username" required>
          <RHFInput name="formUsername" placeholder="Enter username" />
        </RHFInputGroup>

<Button type="submit">
          Submit
        </Button>
      </form>
    </FormProvider>
  );
}
```

## How It Works

RHFInputGroup automatically:

1. **Finds the RHF input component** - Recursively searches children to find the first component with `displayName` containing "rhf" (case-insensitive)
2. **Extracts field name and control** - Gets the `name` and `control` props from the detected input
3. **Renders error messages** - Automatically passes these to [RHFError](/docs/rhf-error) component to display validation errors

This means you don't need to manually specify the field name twice:

```tsx
<RHFInputGroup label="Email">
  <RHFInput name="email" />
</RHFInputGroup>
```

Instead of:

```tsx
<Label>Email</Label>
<RHFInput name="email" />
<RHFError name="email" />
```

## Multiple Inputs

When multiple inputs are present, only the **first input's errors** are shown:

```tsx
<RHFInputGroup label="Phone Number">
  <div className="flex gap-2">
    <RHFInput name="countryCode" placeholder="+1" className="w-20" />
    <RHFInput name="phoneNumber" placeholder="555-0100" />
  </div>
</RHFInputGroup>
```

For multiple inputs with individual error messages, use [RHFError](/docs/rhf-error) manually:

```tsx
<div>
  <Label>Phone Number</Label>
  <div className="flex gap-2">
    <div>
      <RHFInput name="countryCode" placeholder="+1" className="w-20" />
      <RHFError name="countryCode" />
    </div>
    <div>
      <RHFInput name="phoneNumber" placeholder="555-0100" />
      <RHFError name="phoneNumber" />
    </div>
  </div>
</div>
```

## Best Practices

1. **Use for standard layouts** - Perfect for typical label + input + error patterns
2. **Custom layouts** - Use [Label](/docs/label) and [RHFError](/docs/rhf-error) separately for complex layouts
3. **Validation mode** - Use `mode: 'onBlur'` in useForm for better UX:
   ```tsx
   const methods = useForm({
     resolver: zodResolver(schema),
     mode: 'onBlur' // Validates when user leaves the field
   });
   ```
4. **Required fields** - Always use the `required` prop to show asterisk on labels
5. **Help text** - Use `tooltip` prop for additional context without cluttering the UI

## Accessibility

* Inherits all accessibility features from [Label](/docs/label) component
* Proper `htmlFor` attribute linking label to input
* ARIA attributes for required fields
* Error messages properly associated with inputs
* Keyboard navigable
* Screen reader compatible

## Related Components

* [RHFError](/docs/rhf-error) - Error message display component
* [RHFInput](/docs/rhf-input) - Text input with React Hook Form
* [RHFTextarea](/docs/rhf-textarea) - Multi-line text input
* [Label](/docs/label) - Base label component

# RHFInput

import { RHFInput } from '@geckoui/geckoui';
import {
  BasicRHFInputExample,
  WithValidationExample,
  WithPrefixSuffixExample,
  WithTransformExample,
  WithCustomSuffixExample,
  DisabledExample,
  CompleteFormExample
} from '@/components/examples/rhf-input-examples';

# RHFInput

A text input component integrated with React Hook Form that automatically displays error states with a red border when validation fails. Supports value transformation for input/output formatting.

## Installation

```tsx
import { RHFInput } from '@geckoui/geckoui';
```

## Basic Usage

```tsx
import { useForm, FormProvider } from 'react-hook-form';
import { RHFInput } from '@geckoui/geckoui';

function Example() {
  const methods = useForm({
    defaultValues: {
      username: ''
    }
  });

return (
    <FormProvider {...methods}>
      <RHFInput name="username" placeholder="Enter username" />
    </FormProvider>
  );
}
```

## Props API

Extends all props from [Input](/docs/input) component plus:

| Prop        | Type                      | Default       | Description                                                                       |                                               |
| ----------- | ------------------------- | ------------- | --------------------------------------------------------------------------------- | --------------------------------------------- |
| `name`      | `string`                  | -             | Field name (required)                                                             |                                               |
| `control`   | `Control`                 | Auto-injected | Optional: Pass explicitly for nested forms or custom form context                 |                                               |
| `rules`     | `RegisterOptions`         | -             | Inline validation rules (see [Inline Rules Validation](#inline-rules-validation)) |                                               |
| `transform` | `{ input, output }`       | -             | Value transformation functions                                                    |                                               |
| `prefix`    | \`ReactNode \\            | Function\`    | -                                                                                 | Element before input (can access field state) |
| `suffix`    | \`ReactNode \\            | Function\`    | -                                                                                 | Element after input (can access field state)  |
| `onChange`  | `(value: string) => void` | -             | Change callback (receives value, not event)                                       |                                               |
| `onBlur`    | `(value: string) => void` | -             | Blur callback                                                                     |                                               |
| ...rest     | `InputProps`              | -             | All Input component props                                                         |                                               |

## Examples

### With Validation (Zod)

const schema = z.object({
  email: z.string().email('Invalid email address').min(1, 'Email is required')
});

function Example() {
  const methods = useForm({
    resolver: zodResolver(schema),
    mode: 'onBlur', // Validate on blur
    defaultValues: { email: '' }
  });

return (
    <FormProvider {...methods}>
      <RHFInputGroup label="Email Address" required>
        <RHFInput name="email" type="email" placeholder="Enter email" />
      </RHFInputGroup>
    </FormProvider>
  );
}
```

### Inline Rules Validation

For simple forms, you can use the `rules` prop for inline validation instead of a schema resolver:

```tsx
<RHFInput
  name="email"
  rules={{
    required: 'Email is required',
    pattern: {
      value: /^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$/i,
      message: 'Invalid email address'
    }
  }}
/>

<RHFInput
  name="username"
  rules={{
    required: 'Username is required',
    minLength: { value: 3, message: 'Must be at least 3 characters' },
    maxLength: { value: 20, message: 'Must be 20 characters or less' }
  }}
/>
```

**Note:** For complex forms with many fields, we recommend using a schema resolver (Zod, Yup) instead of inline rules for better maintainability and type safety.

### With Prefix and Suffix

```tsx
<RHFInput
  name="amount"
  type="number"
  prefix="$"
  suffix="USD"
  placeholder="0.00"
/>
```

### With Value Transformation

Transform values on input/output (e.g., phone number formatting):

```tsx
const formatPhone = (value: string) => {
  const cleaned = value.replace(/\\D/g, '');
  const match = cleaned.match(/^(\\d{3})(\\d{3})(\\d{4})$/);
  if (match) {
    return `(${match[1]}) ${match[2]}-${match[3]}`;
  }
  return value;
};

const sanitizePhone = (value: string) => {
  return value.replace(/\\D/g, '');
};

<RHFInput
  name="phone"
  placeholder="Phone number"
  transform={{
    input: formatPhone,
    output: sanitizePhone
  }}
/>
```

### Custom Suffix with Error Icon

```tsx
<RHFInput
  name="password"
  type="password"
  suffix={({ fieldState }) => <>fieldState.error ? <ErrorIcon /> : null</>}
/>
```

### Disabled State

```tsx
<RHFInput name="readonly" disabled />
```

### Complete Form Example

const schema = z.object({
  username: z.string().min(3, 'Username must be at least 3 characters'),
  email: z.string().email('Invalid email address'),
  password: z.string().min(8, 'Password must be at least 8 characters')
});

function RegistrationForm() {
  const methods = useForm({
    resolver: zodResolver(schema),
    mode: 'onBlur', // Validate on blur
    defaultValues: {
      username: '',
      email: '',
      password: ''
    }
  });

return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit(console.log)}>
        <RHFInputGroup label="Username" required>
          <RHFInput name="username" placeholder="Enter username" />
        </RHFInputGroup>

<Button type="submit">Submit</Button>
      </form>
    </FormProvider>
  );
}
```

## Error States

RHFInput automatically displays error states with:

* Red border via `GeckoUIRHFInput--error` CSS class when `fieldState.error` exists
* No automatic error icon (you must add via suffix prop if desired)

**Recommended**: Use [RHFInputGroup](/docs/rhf-input-group) for label + input + error layouts. It automatically detects the RHF input and displays validation errors:

```tsx
<RHFInputGroup label="Username" required>
  <RHFInput name="username" />
</RHFInputGroup>
```

Or combine with [RHFError](/docs/rhf-error) component manually:

```tsx
<RHFInput name="username" />
<RHFError name="username" />
```

**Tip**: Use `mode: 'onBlur'` in useForm to validate on blur for better UX:

```tsx
const methods = useForm({
  resolver: zodResolver(schema),
  mode: 'onBlur' // Validates when user leaves the field
});
```

## Value Transformation

The `transform` prop allows formatting values differently for display vs storage:

```tsx
// Currency formatting
<RHFInput
  name="price"
  transform={{
    input: (value) => value ? `$${value}` : '',
    output: (value) => value.replace('$', '')
  }}
/>

// Uppercase transformation
<RHFInput
  name="code"
  transform={{
    input: (value) => value?.toUpperCase() || '',
    output: (value) => value
  }}
/>
```

## Dynamic Prefix/Suffix

Both `prefix` and `suffix` can be functions that receive render props:

```tsx
<RHFInput
  name="email"
  prefix={({ field }) => (
    field.value ? <CheckIcon /> : <MailIcon />
  )}
  suffix={({ fieldState }) => (
    fieldState.error ? <ErrorIcon /> : null
  )}
/>
```

## Accessibility

* Inherits all accessibility features from [Input](/docs/input) component
* Proper ARIA attributes for error states
* Keyboard navigable
* Screen reader compatible

## Related Components

* [Input](/docs/input) - Base input component
* [RHFTextarea](/docs/rhf-textarea) - Multi-line text input
* [RHFNumberInput](/docs/rhf-number-input) - Number-only input
* [RHFError](/docs/rhf-error) - Error message display

# RHFOTPInput

import { RHFOTPInput } from '@geckoui/geckoui';
import {
  BasicRHFOTPInputExample,
  WithValidationExample,
  SixDigitExample,
  FourDigitExample,
  AlphanumericExample,
  DisabledExample,
  CompleteFormExample
} from '@/components/examples/rhf-otp-input-examples';

# RHFOTPInput

An OTP (One-Time Password) input component integrated with React Hook Form that provides a segmented input field for entering verification codes. Each digit is displayed in a separate box with automatic focus management and keyboard navigation. Automatically displays error states with a red border when validation fails.

## Installation

```tsx
import { RHFOTPInput } from '@geckoui/geckoui';
```

## Basic Usage

```tsx
import { useForm, FormProvider } from 'react-hook-form';
import { RHFOTPInput } from '@geckoui/geckoui';

function Example() {
  const methods = useForm({
    defaultValues: {
      basicOtp: ''
    }
  });

return (
    <FormProvider {...methods}>
      <RHFOTPInput name="basicOtp" />
    </FormProvider>
  );
}
```

## Props API

Extends all props from base OTPInput component plus:

| Prop             | Type                      | Default       | Description                                                       |
| ---------------- | ------------------------- | ------------- | ----------------------------------------------------------------- |
| `name`           | `string`                  | -             | Field name (required)                                             |
| `control`        | `Control`                 | Auto-injected | Optional: Pass explicitly for nested forms or custom form context |
| `rules`          | `RegisterOptions`         | -             | Inline validation rules                                           |
| `length`         | `number`                  | 6             | Number of OTP input fields to display                             |
| `numberOnly`     | `boolean`                 | true          | If true, only numeric input is allowed                            |
| `onOTPComplete`  | `(value: string) => void` | -             | Callback when all OTP fields are filled                           |
| `className`      | `string`                  | -             | Wrapper div classname                                             |
| `inputClassName` | `string`                  | -             | Individual input field classname                                  |
| `aspectRatio`    | `string \| number`        | 0.94          | Aspect ratio for each input box                                   |
| `disabled`       | `boolean`                 | false         | Disable all input fields                                          |

## Examples

### With Validation (Zod)

```tsx
import { useForm, FormProvider } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';
import { RHFOTPInput, RHFInputGroup } from '@geckoui/geckoui';

const schema = z.object({
  validationCode: z.string().length(6, 'OTP must be exactly 6 digits').regex(/^\d+$/, 'OTP must contain only numbers')
});

function Example() {
  const methods = useForm({
    resolver: zodResolver(schema),
    mode: 'onBlur',
    defaultValues: { validationCode: '' }
  });

return (
    <FormProvider {...methods}>
      <RHFInputGroup label="Verification Code" required>
        <RHFOTPInput name="validationCode" />
      </RHFInputGroup>
    </FormProvider>
  );
}
```

### Six Digit Code

```tsx
<RHFOTPInput name="sixDigitPin" length={6} />
```

### Four Digit PIN

```tsx
<RHFOTPInput name="fourDigitPin" length={4} />
```

### Alphanumeric Code

```tsx
const schema = z.object({
  activationCode: z.string().length(8, 'Activation code must be exactly 8 characters')
});

<RHFInputGroup label="Activation Code" required>
  <RHFOTPInput name="activationCode" length={8} numberOnly={false} />
</RHFInputGroup>
```

### Disabled State

```tsx
<RHFOTPInput name="disabledOtp" disabled />
```

### Complete Form Example

const schema = z.object({
  twoFactorCode: z.string().length(6, 'Code must be exactly 6 digits').regex(/^\d+$/, 'Code must contain only numbers')
});

function TwoFactorForm() {
  const methods = useForm({
    resolver: zodResolver(schema),
    mode: 'onBlur',
    defaultValues: {
      twoFactorCode: ''
    }
  });

return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit(console.log)}>
        <RHFInputGroup label="Two-Factor Authentication Code" required>
          <RHFOTPInput
            name="twoFactorCode"
            onOTPComplete={(value) => {
              console.log('OTP completed:', value);
            }}
          />
        </RHFInputGroup>

<Button type="submit">Verify Code</Button>
      </form>
    </FormProvider>
  );
}
```

## Inline Rules Validation

For simple validation, use the `rules` prop:

```tsx
<RHFOTPInput
  name="otp"
  rules={{
    required: 'OTP is required',
    minLength: { value: 6, message: 'OTP must be 6 digits' }
  }}
/>
```

For complex forms, we recommend using a schema resolver (Zod, Yup) instead.

## Length Configuration

Configure the number of OTP input fields using the `length` prop:

```tsx
<RHFOTPInput name="pin" length={4} />
<RHFOTPInput name="code" length={6} />
<RHFOTPInput name="activationKey" length={8} />
```

By default, `length` is set to 6 digits.

## Input Mode

Control whether users can enter only numbers or alphanumeric characters:

```tsx
<RHFOTPInput name="numericCode" numberOnly={true} />
<RHFOTPInput name="alphanumericCode" numberOnly={false} />
```

By default, `numberOnly` is `true`, restricting input to numeric characters only.

## OTP Completion Callback

Use `onOTPComplete` to perform actions when all OTP fields are filled:

```tsx
<RHFOTPInput
  name="otp"
  onOTPComplete={(value) => {
    console.log('OTP entered:', value);
    verifyCode(value);
  }}
/>
```

This callback is triggered automatically when the user completes entering all digits.

## Error States

RHFOTPInput automatically displays error states with:

* Red border via `GeckoUIRHFOTPInput--error` CSS class when `fieldState.error` exists
* Individual input fields inherit error styling

Use [RHFInputGroup](/docs/rhf-input-group) component for label + input + error layout:

```tsx
<RHFInputGroup label="Verification Code" required>
  <RHFOTPInput name="code" />
</RHFInputGroup>
```

Or combine with [RHFError](/docs/rhf-error) component manually:

```tsx
<RHFOTPInput name="code" />
<RHFError name="code" />
```

**Tip**: Use `mode: 'onBlur'` in useForm to validate on blur for better UX:

```tsx
const methods = useForm({
  resolver: zodResolver(schema),
  mode: 'onBlur'
});
```

## Validation Patterns

Common Zod validation patterns for OTP inputs:

```tsx
const schema = z.object({
  sixDigitCode: z.string()
    .length(6, 'Code must be exactly 6 digits')
    .regex(/^\d+$/, 'Code must contain only numbers'),

fourDigitPin: z.string()
    .length(4, 'PIN must be exactly 4 digits')
    .regex(/^\d+$/, 'PIN must contain only numbers'),

alphanumericCode: z.string()
    .length(8, 'Code must be exactly 8 characters')
    .regex(/^[A-Za-z0-9]+$/, 'Code must be alphanumeric')
});
```

## Accessibility

* Automatic focus management between input fields
* Keyboard navigation support (arrow keys, backspace, delete)
* Proper ARIA attributes for error states
* Tab navigation support with smart focus handling
* Input mode hints for mobile keyboards (numeric vs text)
* Screen reader compatible

## Keyboard Navigation

* **Numbers/Letters**: Enter value and auto-advance to next field
* **Backspace/Delete**: Remove current value and move to previous field
* **Tab**: Navigate to next unfilled field
* **Enter**: Submit form when last field is filled
* **Paste**: Automatically distribute pasted content across fields

## Related Components

* [OTPInput](/docs/otp-input) - Base OTP input component
* [RHFInput](/docs/rhf-input) - Text input with RHF
* [RHFInputGroup](/docs/rhf-input-group) - Label + input + error layout
* [RHFError](/docs/rhf-error) - Error message display

# RHFRadio

import { RHFRadio } from '@geckoui/geckoui';
import {
  BasicRHFRadioExample,
  WithValidationExample,
  WithStringValuesExample,
  WithBooleanValuesExample,
  WithObjectValuesExample,
  WithArrayValuesExample,
  DisabledExample,
  CompleteFormExample
} from '@/components/examples/rhf-radio-examples';

# RHFRadio

A controlled radio button component for React Hook Form that preserves value types. Unlike native radio inputs that convert values to strings, this component maintains the original data type. Perfect for creating mutually exclusive selection groups.

## Installation

```tsx
import { RHFRadio } from '@geckoui/geckoui';
```

## Basic Usage

```tsx
import { useForm, FormProvider } from 'react-hook-form';
import { RHFRadio } from '@geckoui/geckoui';

function Example() {
  const methods = useForm({
    defaultValues: {
      plan: 'free'
    }
  });

return (
    <FormProvider {...methods}>
      <div className="flex flex-col gap-3">
        <RHFRadio name="plan" value="free" label="Free Plan" />
        <RHFRadio name="plan" value="pro" label="Pro Plan" />
        <RHFRadio name="plan" value="enterprise" label="Enterprise Plan" />
      </div>
    </FormProvider>
  );
}
```

## Props API

Extends all props from [Radio](/docs/radio) component plus:

| Prop             | Type                       | Default       | Description                                                            |
| ---------------- | -------------------------- | ------------- | ---------------------------------------------------------------------- |
| `name`           | `string`                   | -             | Field name (required)                                                  |
| `control`        | `Control`                  | Auto-injected | Optional: Pass explicitly for nested forms or custom form context      |
| `rules`          | `RegisterOptions`          | -             | Inline validation rules                                                |
| `label`          | `ReactNode \| Function`    | -             | Label displayed next to radio                                          |
| `labelClassName` | `string`                   | -             | CSS class for the label                                                |
| `value`          | `unknown`                  | -             | Value to set when selected (required, cannot be `null` or `undefined`) |
| `onChange`       | `(value: unknown) => void` | -             | Change callback                                                        |
| ...rest          | `RadioProps`               | -             | All Radio component props                                              |

## Examples

### With Validation (Zod)

```tsx
import { useForm, FormProvider } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';
import { RHFRadio, RHFInputGroup } from '@geckoui/geckoui';

const schema = z.object({
  plan: z.enum(['free', 'pro', 'enterprise']).refine((val) => val !== undefined, {
    message: 'Please select a plan'
  })
});

function Example() {
  const methods = useForm({
    resolver: zodResolver(schema),
    mode: 'onBlur',
    defaultValues: { plan: undefined }
  });

return (
    <FormProvider {...methods}>
      <RHFInputGroup label="Choose a plan" required>
        <div className="flex flex-col gap-2">
          <RHFRadio name="plan" value="free" label="Free Plan" />
          <RHFRadio name="plan" value="pro" label="Pro Plan" />
          <RHFRadio name="plan" value="enterprise" label="Enterprise Plan" />
        </div>
      </RHFInputGroup>
    </FormProvider>
  );
}
```

### With String Values

```tsx
<div className="flex gap-4">
  <RHFRadio name="size" value="XS" label="XS" />
  <RHFRadio name="size" value="S" label="S" />
  <RHFRadio name="size" value="M" label="M" />
  <RHFRadio name="size" value="L" label="L" />
  <RHFRadio name="size" value="XL" label="XL" />
</div>
```

### With Boolean Values

```tsx
<div className="flex flex-col gap-3">
  <RHFRadio name="enabled" value={true} label="Enabled" />
  <RHFRadio name="enabled" value={false} label="Disabled" />
</div>
```

### With Object Values

```tsx
<div className="flex flex-col gap-3">
  <RHFRadio name="plan" value={{ name: 'free', price: 0 }} label="Free - $0/month" />
  <RHFRadio name="plan" value={{ name: 'pro', price: 9 }} label="Pro - $9/month" />
  <RHFRadio name="plan" value={{ name: 'enterprise', price: 29 }} label="Enterprise - $29/month" />
</div>
```

### With Array Values

```tsx
<div className="flex flex-col gap-3">
  <RHFRadio name="permissions" value={['read']} label="Read Only" />
  <RHFRadio name="permissions" value={['read', 'write']} label="Read & Write" />
  <RHFRadio name="permissions" value={['read', 'write', 'admin']} label="Full Access" />
</div>
```

### Disabled State

```tsx
<div className="flex flex-col gap-3">
  <RHFRadio name="status" value="active" label="Active" />
  <RHFRadio name="status" value="inactive" label="Inactive (Disabled)" disabled />
</div>
```

### Complete Form Example

const schema = z.object({
  plan: z.enum(['free', 'pro', 'enterprise']).refine((val) => val !== undefined, {
    message: 'Please select a plan'
  }),
  paymentMethod: z.enum(['card', 'paypal', 'bank']).refine((val) => val !== undefined, {
    message: 'Please select a payment method'
  }),
  billingCycle: z.enum(['monthly', 'yearly'])
});

function FormExample() {
  const methods = useForm({
    resolver: zodResolver(schema),
    mode: 'onBlur',
    defaultValues: {
      plan: undefined,
      paymentMethod: undefined,
      billingCycle: 'monthly'
    }
  });

return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit(console.log)}>
        <RHFInputGroup label="Choose a plan" required>
          <div className="flex flex-col gap-2">
            <RHFRadio name="plan" value="free" label="Free Plan" />
            <RHFRadio name="plan" value="pro" label="Pro Plan - $9/month" />
            <RHFRadio name="plan" value="enterprise" label="Enterprise Plan - $29/month" />
          </div>
        </RHFInputGroup>

<Button type="submit">Submit</Button>
      </form>
    </FormProvider>
  );
}
```

## Inline Rules Validation

For simple validation, use the `rules` prop:

```tsx
<RHFRadio
  name="plan"
  value="free"
  label="Free Plan"
  rules={{ required: 'Please select a plan' }}
/>
```

For complex forms, we recommend using a schema resolver (Zod, Yup) instead.

## Value Type Preservation

Unlike native HTML radio buttons that convert all values to strings, RHFRadio preserves the original value type:

```tsx
// String values
<RHFRadio name="plan" value="pro" label="Pro Plan" />

// Boolean values
<RHFRadio name="enabled" value={true} label="Yes" />
<RHFRadio name="enabled" value={false} label="No" />

// Number values
<RHFRadio name="quantity" value={10} label="10 items" />

// Object values
<RHFRadio name="config" value={{ theme: "dark", lang: "en" }} label="Dark Theme" />

// Array values
<RHFRadio name="permissions" value={['read', 'write']} label="Read & Write" />
```

The form data will contain the exact value you passed, maintaining its type:

```tsx
// Form submission result:
{
  plan: "pro",           // string
  enabled: true,         // boolean
  quantity: 10,          // number
  config: { theme: "dark", lang: "en" },  // object
  permissions: ['read', 'write']          // array
}
```

## Radio Groups

Radio buttons with the same `name` prop are automatically grouped. Only one radio button in a group can be selected at a time:

```tsx
// All these radios share the same name, creating a mutually exclusive group
<RHFRadio name="plan" value="free" label="Free" />
<RHFRadio name="plan" value="pro" label="Pro" />
<RHFRadio name="plan" value="enterprise" label="Enterprise" />
```

## Value Requirement

The `value` prop is required and cannot be `undefined` or `null`. If you try to use these values, RHFRadio will throw an error:

```tsx
// ❌ Error: value cannot be undefined or null
<RHFRadio name="option" value={undefined} label="Invalid" />
<RHFRadio name="option" value={null} label="Invalid" />

// ✅ Correct: Use any other value type
<RHFRadio name="option" value="" label="Empty string is OK" />
<RHFRadio name="option" value={0} label="Zero is OK" />
<RHFRadio name="option" value={false} label="False is OK" />
```

## Error States

RHFRadio doesn't apply error styling directly. Use [RHFInputGroup](/docs/rhf-input-group) to display errors for the group:

```tsx
<RHFInputGroup label="Choose a plan" required>
  <div className="flex flex-col gap-2">
    <RHFRadio name="plan" value="free" label="Free" />
    <RHFRadio name="plan" value="pro" label="Pro" />
  </div>
</RHFInputGroup>
```

**Tip**: Use `mode: 'onBlur'` in useForm to validate on blur:

```tsx
const methods = useForm({
  resolver: zodResolver(schema),
  mode: 'onBlur'
});
```

## Accessibility

* Inherits all accessibility features from [Radio](/docs/radio) component
* Proper ARIA attributes
* Keyboard navigable (Arrow keys navigate within group, Space selects)
* Screen reader compatible
* Disabled state properly communicated

## Related Components

* [Radio](/docs/radio) - Base radio component
* [RHFCheckbox](/docs/rhf-checkbox) - Multi-select checkboxes
* [RHFSwitch](/docs/rhf-switch) - Toggle switch

# RHFSelect

import { RHFSelect, SelectOption } from '@geckoui/geckoui';
import {
  BasicRHFSelectExample,
  WithValidationExample,
  MultipleSelectExample,
  WithGroupsExample,
  DisabledExample,
  WithOnChangeExample,
  CompleteFormExample
} from '@/components/examples/rhf-select-examples';

# RHFSelect

A select dropdown component integrated with React Hook Form that automatically displays error states with a red border when validation fails. Supports both single and multiple selection modes with keyboard navigation and search capabilities.

## Installation

```tsx
import { RHFSelect, SelectOption } from '@geckoui/geckoui';
```

## Basic Usage

```tsx
import { useForm, FormProvider } from 'react-hook-form';
import { RHFSelect, SelectOption } from '@geckoui/geckoui';

function Example() {
  const methods = useForm({
    defaultValues: {
      basicCountry: ''
    }
  });

return (
    <FormProvider {...methods}>
      <RHFSelect name="basicCountry" placeholder="Select a country">
        <SelectOption value="us" label="United States" />
        <SelectOption value="uk" label="United Kingdom" />
        <SelectOption value="ca" label="Canada" />
        <SelectOption value="au" label="Australia" />
        <SelectOption value="de" label="Germany" />
      </RHFSelect>
    </FormProvider>
  );
}
```

## Props API

Extends all props from [Select](/docs/select) component plus:

| Prop               | Type                        | Default       | Description                                                       |
| ------------------ | --------------------------- | ------------- | ----------------------------------------------------------------- |
| `name`             | `string`                    | -             | Field name (required)                                             |
| `control`          | `Control`                   | Auto-injected | Optional: Pass explicitly for nested forms or custom form context |
| `rules`            | `RegisterOptions`           | -             | Inline validation rules                                           |
| `multiple`         | `boolean`                   | `false`       | Enable multiple selection mode                                    |
| `children`         | `SelectOption[]`            | -             | SelectOption components to render as dropdown options             |
| `onChange`         | `(value: T \| T[]) => void` | -             | Change callback (receives value based on single/multiple mode)    |
| `className`        | `string`                    | -             | Additional CSS class for the select button                        |
| `wrapperClassName` | `string`                    | -             | Additional CSS class for the wrapper div                          |
| `placeholder`      | `string`                    | -             | Placeholder text when no value is selected                        |
| `disabled`         | `boolean`                   | `false`       | Disable the select input                                          |
| ...rest            | `SelectProps`               | -             | All Select component props                                        |

## Examples

### With Validation (Zod)

```tsx
import { useForm, FormProvider } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';
import { RHFSelect, SelectOption, RHFInputGroup } from '@geckoui/geckoui';

const schema = z.object({
  validationSkills: z.string().min(1, 'Please select at least one skill')
});

function Example() {
  const methods = useForm({
    resolver: zodResolver(schema),
    mode: 'onBlur',
    defaultValues: {
      validationSkills: ''
    }
  });

return (
    <FormProvider {...methods}>
      <RHFInputGroup label="Primary Skill" required>
        <RHFSelect name="validationSkills" placeholder="Select your skill">
          <SelectOption value="js" label="JavaScript" />
          <SelectOption value="ts" label="TypeScript" />
          <SelectOption value="react" label="React" />
          <SelectOption value="vue" label="Vue" />
          <SelectOption value="angular" label="Angular" />
        </RHFSelect>
      </RHFInputGroup>
    </FormProvider>
  );
}
```

### Multiple Selection

Enable multiple selection mode to allow users to select multiple options:

```tsx
import { useForm, FormProvider } from 'react-hook-form';
import { RHFSelect, SelectOption } from '@geckoui/geckoui';

function Example() {
  const methods = useForm({
    defaultValues: {
      multipleLanguages: []
    }
  });

return (
    <FormProvider {...methods}>
      <RHFSelect name="multipleLanguages" multiple placeholder="Select languages">
        <SelectOption value="en" label="English" />
        <SelectOption value="es" label="Spanish" />
        <SelectOption value="fr" label="French" />
        <SelectOption value="de" label="German" />
        <SelectOption value="zh" label="Chinese" />
        <SelectOption value="ja" label="Japanese" />
      </RHFSelect>
    </FormProvider>
  );
}
```

### With Option Groups

Organize options into logical groups:

```tsx
<RHFSelect name="groupedCategory" placeholder="Select a category">
  <SelectOption value="electronics" label="Electronics" />
  <SelectOption value="computers" label="Computers" />
  <SelectOption value="phones" label="Phones" />
  <SelectOption value="clothing" label="Clothing" />
  <SelectOption value="shoes" label="Shoes" />
  <SelectOption value="accessories" label="Accessories" />
</RHFSelect>
```

### Disabled State

```tsx
<RHFSelect name="disabledStatus" disabled placeholder="Status">
  <SelectOption value="active" label="Active" />
  <SelectOption value="inactive" label="Inactive" />
  <SelectOption value="pending" label="Pending" />
</RHFSelect>
```

### With onChange Callback

Execute custom logic when the selection changes:

```tsx
<RHFSelect
  name="callbackPriority"
  placeholder="Select priority"
  onChange={(value) => {
    console.log('Selected priority:', value);
  }}
>
  <SelectOption value="low" label="Low" />
  <SelectOption value="medium" label="Medium" />
  <SelectOption value="high" label="High" />
  <SelectOption value="urgent" label="Urgent" />
</RHFSelect>
```

### Complete Form Example

const schema = z.object({
  formCountry: z.string().min(1, 'Country is required'),
  formLanguages: z.array(z.string()).min(1, 'Select at least one language'),
  formPriority: z.string().min(1, 'Priority is required')
});

function RegistrationForm() {
  const methods = useForm({
    resolver: zodResolver(schema),
    mode: 'onBlur',
    defaultValues: {
      formCountry: '',
      formLanguages: [],
      formPriority: ''
    }
  });

return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit(console.log)}>
        <RHFInputGroup label="Country" required>
          <RHFSelect name="formCountry" placeholder="Select your country">
            <SelectOption value="us" label="United States" />
            <SelectOption value="uk" label="United Kingdom" />
            <SelectOption value="ca" label="Canada" />
          </RHFSelect>
        </RHFInputGroup>

<Button type="submit">Submit</Button>
      </form>
    </FormProvider>
  );
}
```

## Inline Rules Validation

For simple validation, use the `rules` prop:

```tsx
<RHFSelect
  name="country"
  placeholder="Select a country"
  rules={{ required: 'Please select a country' }}
>
  <SelectOption value="us" label="United States" />
  <SelectOption value="uk" label="United Kingdom" />
</RHFSelect>
```

For complex forms, we recommend using a schema resolver (Zod, Yup) instead.

## Single vs Multiple Mode

RHFSelect supports two selection modes:

### Single Select (Default)

```tsx
const methods = useForm({
  defaultValues: {
    country: ''
  }
});

<RHFSelect name="country">
  <SelectOption value="us" label="United States" />
  <SelectOption value="uk" label="United Kingdom" />
</RHFSelect>
```

In single select mode:

* Value is a single item of type `T`
* Clicking an option selects it and closes the menu
* Only one option can be selected at a time

### Multiple Select

```tsx
const methods = useForm({
  defaultValues: {
    languages: []
  }
});

<RHFSelect name="languages" multiple>
  <SelectOption value="en" label="English" />
  <SelectOption value="es" label="Spanish" />
</RHFSelect>
```

In multiple select mode:

* Value is an array of type `T[]`
* Clicking an option toggles its selection
* Menu stays open after selection
* Multiple options can be selected

## Validation

Use Zod schema validation for form validation:

```tsx
const schema = z.object({
  singleSelect: z.string().min(1, 'This field is required'),
  multipleSelect: z.array(z.string()).min(1, 'Select at least one option')
});
```

For more complex validation:

```tsx
const schema = z.object({
  skills: z
    .array(z.string())
    .min(2, 'Select at least 2 skills')
    .max(5, 'Select no more than 5 skills')
});
```

**Tip**: Use `mode: 'onBlur'` in useForm to validate when the user leaves the field:

```tsx
const methods = useForm({
  resolver: zodResolver(schema),
  mode: 'onBlur'
});
```

## Error States

RHFSelect automatically displays error states with:

* Red border via `GeckoUIRHFSelectButton--error` CSS class when `fieldState.error` exists
* No automatic error message display (use RHFInputGroup or RHFError component)

Use [RHFInputGroup](/docs/rhf-input-group) component for label + select + error layout:

```tsx
<RHFInputGroup label="Country" required>
  <RHFSelect name="country">
    <SelectOption value="us" label="United States" />
  </RHFSelect>
</RHFInputGroup>
```

Or combine with [RHFError](/docs/rhf-error) component manually:

```tsx
<RHFSelect name="country">
  <SelectOption value="us" label="United States" />
</RHFSelect>
<RHFError name="country" />
```

## Accessibility

* Full keyboard navigation support (Arrow keys, Enter, Escape)
* Built-in search/filter functionality
* Proper ARIA attributes for error states
* Screen reader compatible
* Focus management with visual indicators

## Related Components

* [Select](/docs/select) - Base select component
* [SelectOption](/docs/select-option) - Individual option component
* [RHFInputGroup](/docs/rhf-input-group) - Label and error wrapper
* [RHFError](/docs/rhf-error) - Error message display

# RHFSwitch

import { RHFSwitch } from '@geckoui/geckoui';
import {
  BasicRHFSwitchExample,
  WithCustomValuesExample,
  WithNumberValuesExample,
  WithObjectValuesExample,
  DifferentSizesExample,
  DisabledExample,
  WithValidationExample,
  CompleteFormExample
} from '@/components/examples/rhf-switch-examples';

# RHFSwitch

A controlled toggle switch component for React Hook Form. By default stores boolean values (true/false), but supports custom values of any type. Values maintain their original data types.

## Installation

```tsx
import { RHFSwitch } from '@geckoui/geckoui';
```

## Basic Usage

```tsx
import { useForm, FormProvider } from 'react-hook-form';
import { RHFSwitch } from '@geckoui/geckoui';

function Example() {
  const methods = useForm({
    defaultValues: {
      enabled: false
    }
  });

return (
    <FormProvider {...methods}>
      <div className="flex items-center gap-2">
        <RHFSwitch name="enabled" />
        <span>Enable notifications</span>
      </div>
    </FormProvider>
  );
}
```

## Props API

Extends all props from [Switch](/docs/switch) component plus:

| Prop             | Type                       | Default       | Description                                                       |
| ---------------- | -------------------------- | ------------- | ----------------------------------------------------------------- |
| `name`           | `string`                   | -             | Field name (required)                                             |
| `control`        | `Control`                  | Auto-injected | Optional: Pass explicitly for nested forms or custom form context |
| `rules`          | `RegisterOptions`          | -             | Inline validation rules                                           |
| `value`          | `unknown`                  | -             | Value when checked (if not provided, uses boolean)                |
| `uncheckedValue` | `unknown`                  | -             | Value when unchecked (only with `value` prop)                     |
| `size`           | `'sm' \| 'md' \| 'lg'`     | `'md'`        | Switch size                                                       |
| `onChange`       | `(value: unknown) => void` | -             | Change callback                                                   |
| ...rest          | `SwitchProps`              | -             | All Switch component props                                        |

## Examples

### With Custom String Values

```tsx
<RHFSwitch name="status" value="yes" uncheckedValue="no" />
```

### With Number Values

```tsx
<RHFSwitch name="mode" value={1} uncheckedValue={0} />
```

### With Object Values

```tsx
<RHFSwitch
  name="settings"
  value={{ theme: 'dark', notifications: true }}
  uncheckedValue={{ theme: 'light', notifications: false }}
/>
```

### Different Sizes

```tsx
<RHFSwitch name="small" size="sm" />
<RHFSwitch name="medium" size="md" />
```

### Disabled State

```tsx
<RHFSwitch name="disabledOn" disabled />
<RHFSwitch name="disabledOff" disabled />
```

### With Validation (Zod)

```tsx
import { useForm, FormProvider } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';
import { RHFSwitch, RHFInputGroup } from '@geckoui/geckoui';

const schema = z.object({
  terms: z.literal(true, { message: 'You must accept the terms' })
});

function Example() {
  const methods = useForm({
    resolver: zodResolver(schema),
    mode: 'onBlur',
    defaultValues: { terms: false }
  });

return (
    <FormProvider {...methods}>
      <RHFInputGroup required>
        <div className="flex items-center gap-2">
          <RHFSwitch name="terms" />
          <span>I accept the terms and conditions</span>
        </div>
      </RHFInputGroup>
    </FormProvider>
  );
}
```

### Complete Form Example

const schema = z.object({
  notifications: z.boolean(),
  marketing: z.boolean(),
  darkMode: z.boolean(),
  twoFactor: z.literal(true, { message: 'Two-factor authentication is required' })
});

function FormExample() {
  const methods = useForm({
    resolver: zodResolver(schema),
    mode: 'onBlur',
    defaultValues: {
      notifications: true,
      marketing: false,
      darkMode: false,
      twoFactor: false
    }
  });

return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit(console.log)}>
        <div className="space-y-3">
          <div className="flex items-center justify-between">
            <span>Email notifications</span>
            <RHFSwitch name="notifications" />
          </div>
          <div className="flex items-center justify-between">
            <span>Marketing emails</span>
            <RHFSwitch name="marketing" />
          </div>
          <div className="flex items-center justify-between">
            <span>Dark mode</span>
            <RHFSwitch name="darkMode" />
          </div>
        </div>

<RHFInputGroup required>
          <div className="flex items-center gap-2">
            <RHFSwitch name="twoFactor" />
            <span>Enable two-factor authentication</span>
          </div>
        </RHFInputGroup>

<Button type="submit">Save Settings</Button>
      </form>
    </FormProvider>
  );
}
```

## Inline Rules Validation

For simple validation, use the `rules` prop:

```tsx
<RHFSwitch
  name="terms"
  rules={{ required: 'You must accept the terms' }}
/>
```

For complex forms, we recommend using a schema resolver (Zod, Yup) instead.

## Value Behavior

### Default (Boolean Mode)

When `value` prop is not provided, the switch toggles between `true` and `false`:

```tsx
// Stores: true or false
<RHFSwitch name="enabled" />
```

### Custom Values Mode

When `value` prop is provided:

* **Checked**: Stores the `value`
* **Unchecked**: Stores `uncheckedValue` (default: `undefined`)

```tsx
// Stores: "yes" or "no"
<RHFSwitch name="status" value="yes" uncheckedValue="no" />

// Stores: 1 or 0
<RHFSwitch name="mode" value={1} uncheckedValue={0} />

// Stores: object or undefined
<RHFSwitch name="settings" value={{ enabled: true }} />

// Stores: first object or second object
<RHFSwitch
  name="config"
  value={{ theme: 'dark' }}
  uncheckedValue={{ theme: 'light' }}
/>
```

## Value Type Preservation

RHFSwitch preserves the original value type:

```tsx
// Boolean (default)
<RHFSwitch name="enabled" />
// Result: true or false

// String
<RHFSwitch name="status" value="active" uncheckedValue="inactive" />
// Result: "active" or "inactive"

// Number
<RHFSwitch name="level" value={10} uncheckedValue={0} />
// Result: 10 or 0

// Object
<RHFSwitch name="settings" value={{ a: 1 }} uncheckedValue={{ a: 0 }} />
// Result: { a: 1 } or { a: 0 }

// Array
<RHFSwitch name="permissions" value={['read', 'write']} uncheckedValue={[]} />
// Result: ['read', 'write'] or []
```

## Error States

RHFSwitch doesn't apply error styling directly. Use [RHFInputGroup](/docs/rhf-input-group) to display errors:

```tsx
<RHFInputGroup required>
  <div className="flex items-center gap-2">
    <RHFSwitch name="terms" />
    <span>Accept terms</span>
  </div>
</RHFInputGroup>
```

**Tip**: Use `mode: 'onBlur'` in useForm to validate on blur:

```tsx
const methods = useForm({
  resolver: zodResolver(schema),
  mode: 'onBlur'
});
```

## Keyboard Support

The switch supports full keyboard interaction:

* **Space** or **Enter**: Toggle the switch
* **Tab**: Move focus to/from the switch

## Accessibility

* Inherits all accessibility features from [Switch](/docs/switch) component
* Proper ARIA attributes
* Keyboard accessible
* Screen reader compatible
* Disabled state properly communicated

## Related Components

* [Switch](/docs/switch) - Base switch component
* [RHFCheckbox](/docs/rhf-checkbox) - Checkbox component
* [RHFRadio](/docs/rhf-radio) - Radio button component

# RHFTextarea

import { RHFTextarea } from '@geckoui/geckoui';
import {
  BasicRHFTextareaExample,
  WithValidationExample,
  AutoResizeExample,
  WithRowConstraintsExample,
  DisabledExample,
  CompleteFormExample
} from '@/components/examples/rhf-textarea-examples';

# RHFTextarea

A multi-line textarea component integrated with React Hook Form that automatically displays error states with a red border when validation fails. Supports auto-resizing functionality.

## Installation

```tsx
import { RHFTextarea } from '@geckoui/geckoui';
```

## Basic Usage

```tsx
import { useForm, FormProvider } from 'react-hook-form';
import { RHFTextarea } from '@geckoui/geckoui';

function Example() {
  const methods = useForm({
    defaultValues: {
      description: ''
    }
  });

return (
    <FormProvider {...methods}>
      <RHFTextarea name="description" placeholder="Enter description" />
    </FormProvider>
  );
}
```

## Props API

Extends all props from [Textarea](/docs/textarea) component plus:

| Prop         | Type                      | Default       | Description                                                       |
| ------------ | ------------------------- | ------------- | ----------------------------------------------------------------- |
| `name`       | `string`                  | -             | Field name (required)                                             |
| `control`    | `Control`                 | Auto-injected | Optional: Pass explicitly for nested forms or custom form context |
| `rules`      | `RegisterOptions`         | -             | Inline validation rules                                           |
| `autoResize` | `boolean`                 | `false`       | Enable automatic height adjustment                                |
| `rows`       | `number`                  | `2`           | Minimum number of rows                                            |
| `maxRows`    | `number`                  | -             | Maximum number of rows (only with `autoResize`)                   |
| `onChange`   | `(value: string) => void` | -             | Change callback (receives value, not event)                       |
| `onBlur`     | `(value: string) => void` | -             | Blur callback                                                     |
| ...rest      | `TextareaProps`           | -             | All Textarea component props                                      |

## Examples

### With Validation (Zod)

```tsx
import { useForm, FormProvider } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';
import { RHFTextarea, RHFInputGroup } from '@geckoui/geckoui';

const schema = z.object({
  bio: z.string().min(10, 'Bio must be at least 10 characters').max(500, 'Bio must not exceed 500 characters')
});

function Example() {
  const methods = useForm({
    resolver: zodResolver(schema),
    mode: 'onBlur',
    defaultValues: { bio: '' }
  });

return (
    <FormProvider {...methods}>
      <RHFInputGroup label="Bio" required>
        <RHFTextarea name="bio" placeholder="Tell us about yourself (min 10 chars)" />
      </RHFInputGroup>
    </FormProvider>
  );
}
```

### Auto-Resizing Textarea

```tsx
<RHFTextarea
  name="comments"
  autoResize
  rows={3}
  maxRows={10}
  placeholder="This textarea grows as you type (max 10 rows)"
/>
```

### With Row Constraints

```tsx
<RHFTextarea
  name="notes"
  rows={5}
  placeholder="Fixed at 5 rows"
/>
```

### Disabled State

```tsx
<RHFTextarea name="readonly" disabled />
```

### Complete Form Example

const schema = z.object({
  title: z.string().min(1, 'Title is required'),
  description: z.string().min(20, 'Description must be at least 20 characters'),
  notes: z.string().optional()
});

function FormExample() {
  const methods = useForm({
    resolver: zodResolver(schema),
    mode: 'onBlur',
    defaultValues: {
      title: '',
      description: '',
      notes: ''
    }
  });

return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit(console.log)}>
        <RHFInputGroup label="Title" required>
          <RHFTextarea name="title" rows={1} placeholder="Enter title" />
        </RHFInputGroup>

<Button type="submit">Submit</Button>
      </form>
    </FormProvider>
  );
}
```

## Inline Rules Validation

For simple validation, use the `rules` prop:

```tsx
<RHFTextarea
  name="description"
  rules={{
    required: 'Description is required',
    minLength: { value: 10, message: 'Must be at least 10 characters' }
  }}
/>
```

For complex forms, we recommend using a schema resolver (Zod, Yup) instead.

## Error States

RHFTextarea automatically displays error states with:

* Red border via `GeckoUIRHFTextarea--error` CSS class when `fieldState.error` exists

Use [RHFInputGroup](/docs/rhf-input-group) component for label + textarea + error layout:

```tsx
<RHFInputGroup label="Description" required>
  <RHFTextarea name="description" />
</RHFInputGroup>
```

Or combine with [RHFError](/docs/rhf-error) component manually:

```tsx
<RHFTextarea name="description" />
<RHFError name="description" />
```

**Tip**: Use `mode: 'onBlur'` in useForm to validate on blur for better UX:

```tsx
const methods = useForm({
  resolver: zodResolver(schema),
  mode: 'onBlur'
});
```

## Auto-Resize Behavior

When `autoResize` is enabled:

* Textarea grows automatically as content increases
* Minimum height is determined by the `rows` prop
* Maximum height is determined by the `maxRows` prop
* Shrinks back down when content is removed

When `autoResize` is disabled:

* Textarea has a fixed height based on `rows`
* Users can resize manually (if CSS allows)
* The `maxRows` prop is ignored

## Accessibility

* Inherits all accessibility features from [Textarea](/docs/textarea) component
* Proper ARIA attributes for error states
* Keyboard navigable
* Screen reader compatible

## Related Components

* [Textarea](/docs/textarea) - Base textarea component
* [RHFInput](/docs/rhf-input) - Single-line text input
* [RHFError](/docs/rhf-error) - Error message display

# Spinner

import { Spinner } from '@geckoui/geckoui';

# Spinner

A loading spinner icon component that displays an animated circular indicator. The spinner uses the current text color (via `currentColor`) for its stroke, making it easy to theme by changing the text color of its parent element.

## Installation

```tsx
import { Spinner } from '@geckoui/geckoui';
```

## Basic Usage

```tsx
<Spinner />
```

## Props API

| Prop        | Type            | Default          | Description                 |
| ----------- | --------------- | ---------------- | --------------------------- |
| `stroke`    | `string`        | `'currentColor'` | SVG stroke color            |
| `className` | `string`        | -                | CSS class for styling       |
| ...rest     | `SVGAttributes` | -                | All standard SVG attributes |

## Examples

### Different Sizes

```tsx
<Spinner className="size-4" />
<Spinner className="size-6" />
<Spinner className="size-8" />
<Spinner className="size-12" />
```

### Custom Colors

```tsx
<div className="text-blue-500">
  <Spinner className="size-8" />
</div>

<Spinner stroke="red" className="size-8" />
```

### Loading States

<span>
        Loading...
      </span>
    </div>

<span>
        Processing your request...
      </span>
    </div>

<span>
        Saving changes...
      </span>
    </div>
  </div>
</Preview>

```tsx
<div className="flex items-center gap-2">
  <Spinner className="size-4" />
  <span>Loading...</span>
</div>

<div className="flex items-center gap-2">
  <Spinner className="size-4" />
  <span>Processing your request...</span>
</div>
```

### Centered Loading

```tsx
<div className="flex items-center justify-center h-32">
  <Spinner className="size-8" />
</div>
```

### In Buttons

<span>
        Loading...
      </span>
    </button>

<span>
        Processing
      </span>
    </button>
  </div>
</Preview>

```tsx
<button disabled>
  <Spinner className="size-4" />
  <span>Loading...</span>
</button>
```

### Full Page Loading

<p className="text-gray-600">
          Loading content...
        </p>
      </div>
    </div>
  </div>
</Preview>

```tsx
function FullPageLoading() {
  return (
    <div className="fixed inset-0 flex items-center justify-center bg-white bg-opacity-75 z-50">
      <div className="text-center">
        <Spinner className="size-12 mx-auto mb-2" />
        <p>Loading content...</p>
      </div>
    </div>
  );
}
```

### With LoadingButton

<span>
        Saving...
      </span>
    </button>
  </div>
</Preview>

```tsx
import { LoadingButton } from '@geckoui/geckoui';

<LoadingButton loading={isLoading}>
  Save Changes
</LoadingButton>
```

### Inline with Text

<span>
        Fetching latest data...
      </span>
    </div>

<span className="text-blue-500">
        Syncing with server...
      </span>
    </div>
  </div>
</Preview>

```tsx
<div className="flex items-center gap-2">
  <Spinner className="size-4" />
  <span>Fetching latest data...</span>
</div>
```

## Usage Patterns

### Conditional Rendering

```tsx
function DataComponent() {
  const [loading, setLoading] = useState(true);
  const [data, setData] = useState(null);

if (loading) {
    return (
      <div className="flex items-center justify-center p-8">
        <Spinner className="size-8" />
      </div>
    );
  }

return <div>{/* Render data */}</div>;
}
```

### With Async Operations

```tsx
function AsyncButton() {
  const [loading, setLoading] = useState(false);

const handleClick = async () => {
    setLoading(true);
    await performAsyncOperation();
    setLoading(false);
  };

return (
    <button onClick={handleClick} disabled={loading}>
      {loading ? (
        <>
          <Spinner className="size-4" />
          <span>Processing...</span>
        </>
      ) : (
        <span>Click Me</span>
      )}
    </button>
  );
}
```

## Accessibility

* Uses semantic SVG with `role="status"`
* Includes `aria-label="Loading"` for screen readers
* Animation provides visual feedback
* Should be accompanied by text for context

## Styling

The component uses the class name `GeckoUISpinnerIcon`. The spinner animation is applied via CSS:

```css
.GeckoUISpinnerIcon {
  animation: spin 1s linear infinite;
}

@keyframes spin {
  from { transform: rotate(0deg); }
  to { transform: rotate(360deg); }
}
```

## Color Theming

The spinner uses `currentColor` by default, inheriting the text color from its parent:

```tsx
// Inherits blue color from parent
<div className="text-blue-500">
  <Spinner />
</div>

// Direct color application
<Spinner className="text-red-500" />

// Via stroke prop
<Spinner stroke="#3b82f6" />
```

## Related Components

* [LoadingButton](/docs/loading-button) - Button with built-in spinner
* [Alert](/docs/alert) - Status messages

# Switch

import { Switch } from '@geckoui/geckoui';
import { SwitchBasicExample, SwitchSizesExample, SwitchSettingsPanelExample, SwitchDisabledExample } from '@/components/examples/switch-examples';
import { SwitchCustomSizeExample } from '@/components/examples/module-augmentation-examples';

# Switch

A toggle component built on HeadlessUI that provides an accessible on/off control. Supports multiple sizes, controlled and uncontrolled modes, and integrates seamlessly with forms.

## Installation

```tsx
import { Switch } from '@geckoui/geckoui';
```

## Basic Usage

```tsx
import { useState } from 'react';

function Example() {
  const [enabled, setEnabled] = useState(false);

return (
    <Switch checked={enabled} onChange={setEnabled} />
  );
}
```

## Props API

| Prop             | Type                         | Default | Description                          |
| ---------------- | ---------------------------- | ------- | ------------------------------------ |
| `checked`        | `boolean`                    | -       | Controlled checked state             |
| `onChange`       | `(checked: boolean) => void` | -       | Callback when state changes          |
| `size`           | `'sm' \| 'md'`               | `'md'`  | Size of the switch                   |
| `className`      | `string`                     | -       | CSS class for the switch container   |
| `thumbClassName` | `string`                     | -       | CSS class for the switch thumb       |
| `disabled`       | `boolean`                    | `false` | Disable the switch                   |
| `defaultChecked` | `boolean`                    | -       | Initial checked state (uncontrolled) |

## Examples

### Sizes

```tsx
<div className="flex flex-col gap-4">
  <Switch size="sm" checked={enabled} onChange={setEnabled} />
  <Switch size="md" checked={enabled} onChange={setEnabled} />
</div>
```

### Settings Panel

```tsx
function SettingsPanel() {
  const [settings, setSettings] = useState({
    notifications: true,
    darkMode: false,
    analytics: true,
  });

return (
    <div className="space-y-4">
      <div className="flex items-center justify-between">
        <div>
          <div className="font-medium">Email Notifications</div>
          <div className="text-sm text-gray-500">Receive email updates</div>
        </div>
        <Switch
          checked={settings.notifications}
          onChange={(checked) =>
            setSettings({ ...settings, notifications: checked })
          }
        />
      </div>
      {/* More settings... */}
    </div>
  );
}
```

### Disabled State

```tsx
<div className="flex gap-4">
  <Switch checked disabled />
  <Switch disabled />
</div>
```

### Uncontrolled with Default Value

```tsx
<Switch defaultChecked={true} />
```

## Keyboard Navigation

The switch supports keyboard interaction:

* **Space** or **Enter**: Toggle the switch
* **Tab**: Move focus to next element
* **Shift + Tab**: Move focus to previous element

Note: The Enter key is prevented from default form submission behavior.

## Module Augmentation

The Switch component supports TypeScript module augmentation, allowing you to add custom sizes with full type safety.

### Live Example

This documentation site demonstrates module augmentation with a custom `lg` size:

### Step 1: TypeScript Declaration

Create a declaration file (e.g., `gecko.d.ts`) in your project:

```typescript
import "@geckoui/geckoui";

declare module "@geckoui/geckoui" {
  interface SwitchSizeMap {
    lg: unknown;
  }
}
```

### Step 2: Add CSS Styles

Add the corresponding styles to your global CSS/SCSS file. You need to define both the container size and the thumb element:

```scss
.GeckoUISwitch {
  &--size-lg {
    @apply h-8 w-14;
  }

&__thumb {
    &--size-lg {
      @apply w-6 translate-x-0.5 group-data-[checked]:translate-x-3.5;
    }
  }
}
```

### Step 3: Use Your Custom Size

```tsx
<Switch size="lg" checked={enabled} onChange={setEnabled} />
```

## Accessibility

* Built on HeadlessUI for WCAG compliance
* Proper ARIA attributes automatically applied
* Fully keyboard navigable
* Focus visible for keyboard users
* Works with screen readers
* Disabled state properly communicated

## Styling

The component uses BEM-style class names:

* `GeckoUISwitch` - Main container
* `GeckoUISwitch--size-{sm|md}` - Size modifiers
* `GeckoUISwitch__thumb` - Toggle thumb element
* `GeckoUISwitch__thumb--size-{sm|md}` - Thumb size modifiers

The switch also supports HeadlessUI data attributes:

* `data-[checked]` - Applied when checked
* `data-[disabled]` - Applied when disabled

## Dependencies

This component uses `@headlessui/react` for accessibility and behavior.

## Related Components

* [Checkbox](/docs/checkbox) - For multi-select options
* [Radio](/docs/radio) - For mutually exclusive selections
* [RHFSwitch](/docs/rhf-switch) - React Hook Form integration

# Textarea

import { Textarea } from '@geckoui/geckoui';

# Textarea

A textarea component built on react-textarea-autosize that can automatically adjust its height based on content. Control the minimum and maximum number of rows displayed.

## Installation

```tsx
import { Textarea } from '@geckoui/geckoui';
```

## Basic Usage

```tsx
<Textarea placeholder="Type something..." />
```

## Props API

| Prop         | Type                     | Default | Description                                           |
| ------------ | ------------------------ | ------- | ----------------------------------------------------- |
| `autoResize` | `boolean`                | `false` | Enable automatic height adjustment based on content   |
| `rows`       | `number`                 | `2`     | Minimum number of rows to display                     |
| `maxRows`    | `number`                 | -       | Maximum number of rows (only works with `autoResize`) |
| `className`  | `string`                 | -       | CSS class for styling                                 |
| `disabled`   | `boolean`                | `false` | Disable the textarea                                  |
| `readOnly`   | `boolean`                | `false` | Make the textarea read-only                           |
| ...rest      | `TextareaHTMLAttributes` | -       | All standard HTML textarea attributes                 |

## Examples

### Auto-Resizing Textarea

```tsx
<Textarea
  autoResize
  placeholder="This textarea grows as you type..."
/>
```

### With Row Constraints

```tsx
<Textarea
  rows={4}
  placeholder="Fixed at 4 rows"
/>
```

### Auto-Resize with Max Rows

```tsx
<Textarea
  autoResize
  rows={2}
  maxRows={8}
  placeholder="Grows from 2 to 8 rows, then scrolls..."
/>
```

### Disabled State

```tsx
<Textarea
  disabled
  placeholder="This textarea is disabled"
  value="Cannot edit this content"
/>
```

### Read-Only State

```tsx
<Textarea
  readOnly
  value="This is read-only content that cannot be edited."
  rows={3}
/>
```

## Auto-Resize Behavior

When `autoResize` is enabled:

* The textarea grows automatically as content increases
* Minimum height is determined by the `rows` prop
* Maximum height is determined by the `maxRows` prop
* Shrinks back down when content is removed

When `autoResize` is disabled:

* The textarea has a fixed height
* Users can resize manually (unless CSS prevents it)
* The `maxRows` prop is ignored

## Accessibility

* Fully keyboard navigable
* Works with screen readers
* Supports all ARIA textarea attributes
* Disabled state is properly communicated

## Styling

The component uses the class name `GeckoUITextarea`. Override styles using the `className` prop:

```css
.GeckoUITextarea {
  /* Your custom styles */
}
```

## Dependencies

This component uses `react-textarea-autosize` for the auto-resize functionality.

## Related Components

* [Input](/docs/input) - Single-line text input
* [Label](/docs/label) - Form labels
* [InputError](/docs/input-error) - Error messages
* [RHFTextarea](/docs/rhf-textarea) - React Hook Form integration

# Theming

Gecko UI uses CSS custom properties (variables) for theming. All color values use RGB format without the `rgb()` wrapper, allowing for easy opacity adjustments.

## CSS Variables

The library uses a comprehensive set of CSS variables organized into categories:

### Primary Colors

Primary color scale from 50 (lightest) to 950 (darkest):

```css
:root {
  --gecko-ui-primary-50: 255 248 235;
  --gecko-ui-primary-100: 255 235 204;
  --gecko-ui-primary-200: 255 214 153;
  --gecko-ui-primary-300: 255 184 96;
  --gecko-ui-primary-400: 255 149 51;
  --gecko-ui-primary-500: 255 115 21;   /* Base primary */
  --gecko-ui-primary-600: 236 93 14;
  --gecko-ui-primary-700: 200 70 8;
  --gecko-ui-primary-800: 150 48 5;
  --gecko-ui-primary-900: 110 35 3;
  --gecko-ui-primary-950: 72 24 1;
}
```

### Surface Colors

Background colors for various UI surfaces:

```css
:root {
  --gecko-ui-surface-primary: 255 255 255;        /* Main background */
  --gecko-ui-surface-secondary: 250 250 250;      /* Secondary background */
  --gecko-ui-surface-tertiary: 245 245 245;       /* Tertiary background */
  --gecko-ui-surface-hover: 245 245 245;          /* Hover state */
  --gecko-ui-surface-hover-strong: 235 235 235;   /* Strong hover state */
  --gecko-ui-surface-active: 212 212 212;         /* Active/pressed state */
  --gecko-ui-surface-disabled: 235 235 235;       /* Disabled state */
  --gecko-ui-surface-overlay: 0 0 0;              /* Backdrop overlay */
  --gecko-ui-surface-autofill: 245 245 245;       /* Browser autofill */
}
```

### Text Colors

Text colors for different hierarchy levels:

```css
:root {
  --gecko-ui-text-primary: 23 23 23;         /* Primary text */
  --gecko-ui-text-secondary: 64 64 64;       /* Secondary text */
  --gecko-ui-text-tertiary: 115 115 115;     /* Tertiary text */
  --gecko-ui-text-disabled: 163 163 163;     /* Disabled text */
  --gecko-ui-text-placeholder: 163 163 163;  /* Placeholder text */
  --gecko-ui-text-inverse: 250 250 250;      /* Inverse text (on dark) */
  --gecko-ui-text-muted: 115 115 115;        /* Muted text */
}
```

### Border Colors

Border colors for various states:

```css
:root {
  --gecko-ui-border-primary: 235 235 235;    /* Default border */
  --gecko-ui-border-secondary: 212 212 212;  /* Secondary border */
  --gecko-ui-border-focus: 163 163 163;      /* Focus state */
  --gecko-ui-border-hover: 212 212 212;      /* Hover state */
  --gecko-ui-border-disabled: 235 235 235;   /* Disabled state */
}
```

### Scrollbar Colors

Custom scrollbar styling:

```css
:root {
  --gecko-ui-scrollbar-track: 0 0 0 / 0;          /* Scrollbar track (transparent) */
  --gecko-ui-scrollbar-thumb: 209 213 219;        /* Scrollbar thumb */
  --gecko-ui-scrollbar-thumb-hover: 156 163 175;  /* Scrollbar thumb on hover */
}
```

## Dark Mode

Gecko UI includes built-in dark mode support. Apply the `.dark` class to enable dark theme:

```css
.dark {
  /* Primary colors remain the same */
  --gecko-ui-primary-500: 255 115 21;

/* Surface colors inverted */
  --gecko-ui-surface-primary: 23 23 23;
  --gecko-ui-surface-secondary: 32 32 32;
  --gecko-ui-surface-tertiary: 45 45 45;
  --gecko-ui-surface-hover: 45 45 45;
  --gecko-ui-surface-hover-strong: 64 64 64;
  --gecko-ui-surface-active: 115 115 115;
  --gecko-ui-surface-disabled: 45 45 45;
  --gecko-ui-surface-overlay: 0 0 0;
  --gecko-ui-surface-autofill: 32 32 32;

/* Text colors inverted */
  --gecko-ui-text-primary: 250 250 250;
  --gecko-ui-text-secondary: 212 212 212;
  --gecko-ui-text-tertiary: 163 163 163;
  --gecko-ui-text-disabled: 115 115 115;
  --gecko-ui-text-placeholder: 115 115 115;
  --gecko-ui-text-inverse: 23 23 23;
  --gecko-ui-text-muted: 163 163 163;

/* Borders with opacity for dark mode */
  --gecko-ui-border-primary: 255 255 255 / 0.1;
  --gecko-ui-border-secondary: 255 255 255 / 0.15;
  --gecko-ui-border-focus: 115 115 115;
  --gecko-ui-border-hover: 163 163 163;
  --gecko-ui-border-disabled: 255 255 255 / 0.1;

/* Scrollbar colors for dark mode */
  --gecko-ui-scrollbar-track: 0 0 0 / 0;
  --gecko-ui-scrollbar-thumb: 75 85 99;
  --gecko-ui-scrollbar-thumb-hover: 107 114 128;
}
```

### Implementing Dark Mode

Add the `dark` class to your root element:

```tsx
import { useState } from 'react';

function App() {
  const [isDark, setIsDark] = useState(false);

return (
    <div className={isDark ? 'dark' : ''}>
      <button onClick={() => setIsDark(!isDark)}>
        Toggle Dark Mode
      </button>
      {/* Your app content */}
    </div>
  );
}
```

Or apply it to the `<html>` element:

```tsx
'use client';

import { useEffect, useState } from 'react';

export function ThemeProvider({ children }) {
  const [theme, setTheme] = useState<'light' | 'dark'>('light');

useEffect(() => {
    // Apply theme to html element
    document.documentElement.classList.toggle('dark', theme === 'dark');
  }, [theme]);

return <>{children}</>;
}
```

## Customizing Colors

### Changing Primary Color

Override the primary color scale to match your brand:

```css
:root {
  /* Blue primary color */
  --gecko-ui-primary-50: 239 246 255;
  --gecko-ui-primary-100: 219 234 254;
  --gecko-ui-primary-200: 191 219 254;
  --gecko-ui-primary-300: 147 197 253;
  --gecko-ui-primary-400: 96 165 250;
  --gecko-ui-primary-500: 59 130 246;   /* Base primary */
  --gecko-ui-primary-600: 37 99 235;
  --gecko-ui-primary-700: 29 78 216;
  --gecko-ui-primary-800: 30 64 175;
  --gecko-ui-primary-900: 30 58 138;
  --gecko-ui-primary-950: 23 37 84;
}
```

### Customizing Specific Colors

Override individual tokens:

```css
:root {
  /* Make borders more prominent */
  --gecko-ui-border-primary: 200 200 200;

/* Adjust text hierarchy */
  --gecko-ui-text-secondary: 80 80 80;

/* Custom hover states */
  --gecko-ui-surface-hover: 240 240 240;
}
```

## Using RGB Values

All colors use RGB format (space-separated values) to enable easy opacity adjustments:

```css
/* Use with rgb() */
color: rgb(var(--gecko-ui-text-primary));

/* Use with opacity */
color: rgb(var(--gecko-ui-text-primary) / 0.5);
background: rgb(var(--gecko-ui-surface-primary) / 0.8);

/* Use in Tailwind arbitrary values */
className="text-[rgb(var(--gecko-ui-text-primary))]"
className="bg-[rgb(var(--gecko-ui-surface-hover)/0.5)]"
```

## Component-Specific Styling

Components use their own class names for targeted styling:

```css
/* Style all inputs */
.GeckoUIInput {
  --gecko-ui-border-primary: 180 180 180;
}

/* Style all buttons */
.GeckoUIButton {
  border-radius: 0.5rem;
}

/* Style specific button variant */
.GeckoUIButton--filled {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}
```

## Customizing Icons

Gecko UI uses CSS `mask-image` with inline SVGs for icons. This approach allows icons to inherit color from parent elements and be styled with CSS.

To find an icon's class name, use your browser's DevTools to inspect the element. All icon classes follow the BEM naming convention (e.g., `.GeckoUI-icon__check`, `.GeckoUIAlert__icon--error`).

### Overriding an Icon

To replace an icon, override the `mask-image` property with your custom SVG:

```css
.GeckoUI-icon__check {
  mask-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3"><polyline points="20 6 9 17 4 12"/></svg>');
  -webkit-mask-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3"><polyline points="20 6 9 17 4 12"/></svg>');
}
```

### Overriding Alert Icons

Alert icons are variant-specific. Override them by targeting the variant modifier:

```css
.GeckoUIAlert__icon--error {
  @apply bg-red-600;
  mask-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor"><path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm-1 15v-2h2v2h-2zm0-4V7h2v6h-2z"/></svg>');
  -webkit-mask-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor"><path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm-1 15v-2h2v2h-2zm0-4V7h2v6h-2z"/></svg>');
}
```

### Icon Styling Properties

Icons use these CSS properties which you can also customize:

```css
.GeckoUI-icon__check {
  mask-position: center;
  mask-size: contain;
  mask-repeat: no-repeat;
  -webkit-mask-position: center;
  -webkit-mask-size: contain;
  -webkit-mask-repeat: no-repeat;
}
```

### Using External Icon Libraries

You can also use icons from external libraries by converting them to data URLs:

```css
/* Using a Lucide icon */
.GeckoUI-icon__arrow-down {
  mask-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m6 9 6 6 6-6"/></svg>');
  -webkit-mask-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m6 9 6 6 6-6"/></svg>');
}
```

## Best Practices

1. **Use RGB Format**: All custom colors should use RGB values (e.g., `255 255 255`) for opacity support
2. **Maintain Consistency**: Keep color scales consistent with 50-950 range
3. **Test Contrast**: Ensure text colors meet WCAG contrast requirements
4. **Dark Mode Parity**: When customizing light mode, also update dark mode tokens
5. **Component Overrides**: Use component-specific classes (`.GeckoUIButton`) rather than global tokens when possible

## Example: Complete Custom Theme

```css
/* custom-theme.css */
:root {
  /* Brand primary color (Purple) */
  --gecko-ui-primary-50: 250 245 255;
  --gecko-ui-primary-100: 243 232 255;
  --gecko-ui-primary-200: 233 213 255;
  --gecko-ui-primary-300: 216 180 254;
  --gecko-ui-primary-400: 192 132 252;
  --gecko-ui-primary-500: 168 85 247;   /* Base */
  --gecko-ui-primary-600: 147 51 234;
  --gecko-ui-primary-700: 126 34 206;
  --gecko-ui-primary-800: 107 33 168;
  --gecko-ui-primary-900: 88 28 135;
  --gecko-ui-primary-950: 59 7 100;

/* Custom border radius */
  --gecko-ui-border-radius: 0.75rem;
}

/* Apply to components */
.GeckoUIInput,
.GeckoUITextarea,
.GeckoUIButton {
  border-radius: var(--gecko-ui-border-radius);
}
```

Import after the base styles:

```tsx
import '@geckoui/geckoui/styles.css';
import './custom-theme.css';
```

## Next Steps

* [Installation](/docs/installation) - Setup guide

# Toast

import { toast } from '@geckoui/geckoui';
import { BasicToastExample, ToastVariantsExample, ToastWithDescriptionExample, ToastWithActionExample, PromiseToastExample, CustomDurationExample, LoadingToastExample, DismissToastExample, CustomStyledToastExample, RichContentToastExample, PositionExample } from '@/components/examples/toast-examples';

# Toast

Display brief, non-intrusive notification messages to provide feedback on user actions. Built on [Sonner](https://sonner.emilkowal.ski/), featuring automatic stacking, promise handling, and rich customization options.

## Installation

```tsx
import { toast, GeckoUIPortal } from '@geckoui/geckoui';
```

## Setup

Add `GeckoUIPortal` to your app root to enable toast notifications:

```tsx
// app/layout.tsx or _app.tsx
import { GeckoUIPortal } from '@geckoui/geckoui';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <GeckoUIPortal />
      </body>
    </html>
  );
}
```

## Basic Usage

```tsx
'use client';

import { toast, Button } from '@geckoui/geckoui';

function Example() {
  return (
    <Button onClick={() => toast('This is a basic toast notification')}>
      Show Toast
    </Button>
  );
}
```

## Toast API

### `toast(message, options?)`

Display a default toast notification.

```tsx
toast('Hello World');
toast('Hello World', { duration: 5000 });
```

### Variant Methods

| Method                             | Description                      |
| ---------------------------------- | -------------------------------- |
| `toast.success(message, options?)` | Success notification (green)     |
| `toast.error(message, options?)`   | Error notification (red)         |
| `toast.warning(message, options?)` | Warning notification (yellow)    |
| `toast.info(message, options?)`    | Info notification (blue)         |
| `toast.loading(message, options?)` | Loading state with spinner       |
| `toast.promise(promise, messages)` | Automatic promise state handling |

### Control Methods

| Method                              | Description                            |
| ----------------------------------- | -------------------------------------- |
| `toast.dismiss(id?)`                | Dismiss a specific toast or all toasts |
| `toast.custom(component, options?)` | Display a custom component             |

## Options

| Option        | Type                                                                                              | Default          | Description                                    |
| ------------- | ------------------------------------------------------------------------------------------------- | ---------------- | ---------------------------------------------- |
| `description` | `string \| ReactNode`                                                                             | -                | Additional description below the message       |
| `duration`    | `number`                                                                                          | `4000`           | Duration in ms (use `Infinity` for persistent) |
| `position`    | `'top-left' \| 'top-center' \| 'top-right' \| 'bottom-left' \| 'bottom-center' \| 'bottom-right'` | `'bottom-right'` | Toast position on screen                       |
| `action`      | `{ label: string; onClick: () => void }`                                                          | -                | Action button                                  |
| `cancel`      | `{ label: string; onClick: () => void }`                                                          | -                | Cancel button                                  |
| `id`          | `string \| number`                                                                                | -                | Custom toast ID                                |
| `onDismiss`   | `() => void`                                                                                      | -                | Callback when dismissed                        |
| `onAutoClose` | `() => void`                                                                                      | -                | Callback when auto-closed                      |
| `className`   | `string`                                                                                          | -                | Custom CSS class                               |
| `style`       | `CSSProperties`                                                                                   | -                | Inline styles                                  |
| `closeButton` | `boolean`                                                                                         | `false`          | Show close button                              |

## Examples

### Toast Variants

```tsx
<Button onClick={() => toast.success('Operation completed successfully!')}>
  Success
</Button>

<Button onClick={() => toast.error('An error occurred!')}>
  Error
</Button>

<Button onClick={() => toast.warning('This is a warning message')}>
  Warning
</Button>

<Button onClick={() => toast.info('Here is some information')}>
  Info
</Button>
```

### With Description

```tsx
toast.success('Account created', {
  description: 'Your account has been created successfully. You can now sign in.'
});

toast.error('Upload failed', {
  description: 'The file size exceeds the 10MB limit. Please choose a smaller file.'
});
```

### With Action Button

```tsx
toast('Email sent', {
  description: 'Your email has been sent to john@example.com',
  action: {
    label: 'Undo',
    onClick: () => toast.info('Email sending cancelled')
  }
});
```

### Promise Toast

Automatically handles loading, success, and error states:

```tsx
'use client';

import { toast, Button } from '@geckoui/geckoui';

function Example() {
  const downloadReport = async () => {
    const response = await fetch('/api/report');
    if (!response.ok) throw new Error('Download failed');
    return response.json();
  };

return (
    <Button
      onClick={() =>
        toast.promise(downloadReport(), {
          loading: 'Downloading report...',
          success: (data) => `${data.name} downloaded successfully`,
          error: 'Download failed. Please try again.'
        })
      }
    >
      Download Report
    </Button>
  );
}
```

### Custom Duration

```tsx
// Quick message (1 second)
toast('Quick message', { duration: 1000 });

// Normal message (4 seconds - default)
toast('Normal message', { duration: 4000 });

// Persistent message (stays until dismissed)
toast('Persistent message', { duration: Infinity });
```

### Loading Toast

```tsx
function Example() {
  const handleProcess = () => {
    const toastId = toast.loading('Processing your request...');

// Simulate async operation
    setTimeout(() => {
      toast.success('Process completed!', { id: toastId });
    }, 3000);
  };

return <Button onClick={handleProcess}>Start Process</Button>;
}
```

### Dismiss Toasts

```tsx
// Dismiss a specific toast
const id = toast('This toast can be dismissed manually');
toast.dismiss(id);

// Dismiss all toasts
toast.dismiss();

// Auto-dismiss after delay
const toastId = toast('Auto-dismissing...', { duration: Infinity });
setTimeout(() => toast.dismiss(toastId), 3000);
```

### Custom Styling

```tsx
toast('Custom styled toast', {
  className: 'border-2 border-blue-500',
  style: {
    background: 'rgb(var(--gecko-ui-surface-secondary))'
  }
});
```

### Rich Content

```tsx
toast(
  <div>
    <strong className="block text-sm font-semibold">New Feature Available</strong>
    <p className="text-sm mt-1">
      Check out our new dashboard analytics with real-time data visualization.
    </p>
  </div>,
  { duration: 5000 }
);
```

### Toast Positions

```tsx
toast('Top Left', { position: 'top-left' });
toast('Top Center', { position: 'top-center' });
toast('Top Right', { position: 'top-right' });
toast('Bottom Left', { position: 'bottom-left' });
toast('Bottom Center', { position: 'bottom-center' });
toast('Bottom Right', { position: 'bottom-right' });
```

## Global Configuration

Configure toast defaults in `GeckoUIPortal`:

```tsx
<GeckoUIPortal
  toastOptions={{
    position: 'top-right',
    duration: 3000,
    closeButton: true,
    richColors: true,
    className: 'my-toast',
    style: {
      background: 'white',
      color: 'black'
    }
  }}
/>
```

### Available Global Options

| Option          | Type                            | Default          | Description                     |
| --------------- | ------------------------------- | ---------------- | ------------------------------- |
| `position`      | `Position`                      | `'bottom-right'` | Default position                |
| `duration`      | `number`                        | `4000`           | Default duration                |
| `closeButton`   | `boolean`                       | `false`          | Show close button on all toasts |
| `richColors`    | `boolean`                       | `false`          | Enhanced colors for variants    |
| `expand`        | `boolean`                       | `false`          | Expand toasts on hover          |
| `visibleToasts` | `number`                        | `3`              | Max visible toasts              |
| `gap`           | `number`                        | `14`             | Gap between toasts              |
| `offset`        | `string`                        | -                | Offset from edge                |
| `theme`         | `'light' \| 'dark' \| 'system'` | `'light'`        | Color theme                     |

## Accessibility

* Toasts are announced by screen readers
* Automatically removed after duration expires
* Action buttons are keyboard accessible
* Supports `prefers-reduced-motion` for animations
* ARIA live regions for dynamic content

## Best Practices

1. **Keep messages brief**: Toast messages should be short and scannable
2. **Use appropriate variants**: Match the toast type to the message (success, error, etc.)
3. **Provide actions when needed**: Allow users to undo or retry failed operations
4. **Don't overuse**: Avoid showing too many toasts at once
5. **Set appropriate durations**:
   * Success: 2-4 seconds
   * Error: 5-7 seconds (or with action)
   * Loading: Until operation completes
6. **Position wisely**: Bottom-right is least intrusive for most layouts
7. **Avoid critical information**: Don't use toasts for important information that users must read

## Related Components

* [Alert](/docs/alert) - Display prominent alerts in content
* [Dialog](/docs/dialog) - Modal dialogs for important messages

## Resources

* [Sonner Documentation](https://sonner.emilkowal.ski/)

# Tooltip

import { Tooltip, Button } from '@geckoui/geckoui';

# Tooltip

Tooltip displays contextual information in a floating overlay when users hover over or focus on an element. Built on Radix UI, it provides accessible tooltips with customizable positioning, delays, and styling.

## Installation

```tsx
import { Tooltip } from '@geckoui/geckoui';
```

## Basic Usage

<Preview>
  <Tooltip content="This is a tooltip" triggerAsChild>
    <Button>
      Hover me
    </Button>
  </Tooltip>
</Preview>

```tsx
<Tooltip content="This is a tooltip" triggerAsChild>
  <Button>Hover me</Button>
</Tooltip>
```

## Props API

| Prop               | Type                                     | Default     | Description                |
| ------------------ | ---------------------------------------- | ----------- | -------------------------- |
| `content`          | `string \| ReactNode \| FC`              | -           | Tooltip content            |
| `side`             | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'`     | Tooltip position           |
| `delayDuration`    | `number`                                 | `700`       | Delay before showing (ms)  |
| `sideOffset`       | `number`                                 | `5`         | Distance from trigger (px) |
| `backgroundColor`  | `string`                                 | `'#4b5563'` | Tooltip background color   |
| `className`        | `string`                                 | -           | CSS class for tooltip      |
| `triggerClassName` | `string`                                 | -           | CSS class for trigger      |
| `triggerAsChild`   | `boolean`                                | `false`     | Merge trigger with child   |
| `children`         | `ReactNode`                              | -           | Trigger element (required) |

## Examples

### Different Positions

<Tooltip content="Right tooltip" side="right" triggerAsChild>
      <Button size="sm">
        Right
      </Button>
    </Tooltip>

<Tooltip content="Bottom tooltip" side="bottom" triggerAsChild>
      <Button size="sm">
        Bottom
      </Button>
    </Tooltip>

```tsx
<Tooltip content="Top tooltip" side="top" triggerAsChild>
  <Button>Top</Button>
</Tooltip>

<Tooltip content="Right tooltip" side="right" triggerAsChild>
  <Button>Right</Button>
</Tooltip>

<Tooltip content="Bottom tooltip" side="bottom" triggerAsChild>
  <Button>Bottom</Button>
</Tooltip>

<Tooltip content="Left tooltip" side="left" triggerAsChild>
  <Button>Left</Button>
</Tooltip>
```

### Icon Buttons

```tsx
<Tooltip content="Add new item" side="right" delayDuration={300} triggerAsChild>
  <Button variant="icon">
    <PlusIcon />
  </Button>
</Tooltip>

<Tooltip content="Edit item" side="right" delayDuration={300} triggerAsChild>
  <Button variant="icon">
    <EditIcon />
  </Button>
</Tooltip>
```

### Complex Content

<Preview>
  <Tooltip
    content={
    <div>
      <div className="font-semibold">Premium Feature</div>
      <div className="text-sm">Upgrade to access this feature</div>
    </div>
  }
    backgroundColor="#1f2937"
    sideOffset={10}
    triggerAsChild
  >
    <Button variant="outlined">
      🔒 Locked Feature
    </Button>
  </Tooltip>
</Preview>

```tsx
<Tooltip
  content={
    <div>
      <strong>Premium Feature</strong>
      <p>Upgrade to access this feature</p>
    </div>
  }
  backgroundColor="#1f2937"
  sideOffset={10}
  triggerAsChild
>
  <Button variant="outlined">
    <LockIcon />
    <span>Locked Feature</span>
  </Button>
</Tooltip>
```

### Custom Delay

<Preview>
  <div className="flex items-center gap-4">
    <Tooltip content="Instant tooltip" delayDuration={0} triggerAsChild>
      <Button size="sm">
        No delay
      </Button>
    </Tooltip>

```tsx
<Tooltip content="Instant tooltip" delayDuration={0} triggerAsChild>
  <Button>No delay</Button>
</Tooltip>

<Tooltip content="Standard tooltip" delayDuration={700} triggerAsChild>
  <Button>700ms (default)</Button>
</Tooltip>
```

### Custom Colors

<Tooltip content="Green tooltip" backgroundColor="#10b981" triggerAsChild>
      <Button size="sm">
        Green
      </Button>
    </Tooltip>
  </div>
</Preview>

```tsx
<Tooltip content="Blue tooltip" backgroundColor="#3b82f6" triggerAsChild>
  <Button>Blue</Button>
</Tooltip>

<Tooltip content="Red tooltip" backgroundColor="#ef4444" triggerAsChild>
  <Button>Red</Button>
</Tooltip>
```

### Info Hints

<Preview>
  <div className="space-y-3">
    <Tooltip content="Last updated: 2 hours ago" side="bottom" delayDuration={500}>
      <span className="inline-flex items-center gap-1 cursor-help border-b border-dashed">
        Status: Active ℹ️
      </span>
    </Tooltip>

<Tooltip content="This action cannot be undone" side="right" backgroundColor="#ef4444" triggerAsChild>
      <Button variant="filled" className="bg-red-500">
        Delete Account
      </Button>
    </Tooltip>
  </div>
</Preview>

```tsx
<Tooltip
  content="Last updated: 2 hours ago"
  side="bottom"
  delayDuration={500}
>
  <span>Status: Active</span>
</Tooltip>

<Tooltip
  content="This action cannot be undone"
  backgroundColor="#ef4444"
  triggerAsChild
>
  <Button>Delete Account</Button>
</Tooltip>
```

### With Offset

<Preview>
  <div className="flex items-center gap-8 py-8">
    <Tooltip content="Close to trigger" sideOffset={2} triggerAsChild>
      <Button size="sm">
        Offset: 2px
      </Button>
    </Tooltip>

<Tooltip content="Default distance" sideOffset={5} triggerAsChild>
      <Button size="sm">
        Offset: 5px
      </Button>
    </Tooltip>

<Tooltip content="Far from trigger" sideOffset={15} triggerAsChild>
      <Button size="sm">
        Offset: 15px
      </Button>
    </Tooltip>
  </div>
</Preview>

```tsx
<Tooltip content="Close to trigger" sideOffset={2} triggerAsChild>
  <Button>Offset: 2px</Button>
</Tooltip>

<Tooltip content="Far from trigger" sideOffset={15} triggerAsChild>
  <Button>Offset: 15px</Button>
</Tooltip>
```

### Disabled Buttons

<Preview>
  <Tooltip content="This feature is currently disabled" triggerAsChild>
    <Button disabled>
      Disabled Button
    </Button>
  </Tooltip>
</Preview>

```tsx
<Tooltip content="This feature is currently disabled" triggerAsChild>
  <Button disabled>Disabled Button</Button>
</Tooltip>
```

## Behavior

### No Content

If no `content` prop is provided, the tooltip returns children unchanged without any wrapper:

```tsx
<Tooltip>
  <Button>No tooltip</Button>
</Tooltip>
// Renders: <Button>No tooltip</Button>
```

### Trigger as Child

Use `triggerAsChild={true}` to avoid invalid HTML nesting (like button inside button) and prevent hydration errors in Next.js. This is especially important when using focusable elements like Button:

```tsx
<Tooltip content="Tooltip text" triggerAsChild>
  <Button>I am a button</Button>
</Tooltip>
```

This prevents the invalid HTML structure:

```html

<button type="button">
  <button>I am a button</button>
</button>

<button>I am a button</button>
```

**Important**: In Next.js, `<button>` cannot be a descendant of `<button>`. Always use `triggerAsChild` when the child is a focusable element like Button.

### Arrow Display

The tooltip arrow is displayed only for `top` and `bottom` positions. It matches the `backgroundColor` prop.

## Accessibility

* Built on Radix UI for WCAG compliance
* Proper ARIA attributes automatically applied
* Keyboard accessible (focus shows tooltip)
* Works with screen readers
* `role="tooltip"` on trigger and content
* Hover and focus both trigger display

## Styling

The component uses BEM-style class names:

* `GeckoUITooltip` - Tooltip content container
* `GeckoUITooltip__trigger` - Trigger wrapper (when `triggerAsChild={false}`)
* `GeckoUITooltip__arrow` - Arrow element

Override styles using `className` for content or `triggerClassName` for trigger.

## Dependencies

This component uses `@radix-ui/react-tooltip` for accessibility and behavior.

## Related Components

* [Label](/docs/label) - Labels with built-in tooltips
* [Alert](/docs/alert) - Page-level messages

# Advanced Usage

import {
  ConditionalRenderingExample,
  CustomActionsExample,
  DebugViewExample,
  ProgrammaticControlExample,
  SelectConsumerExample
} from "@/components/examples/select/advanced-examples";
import { Button, Select, SelectConsumer, SelectOption } from "@geckoui/geckoui";

# Advanced Usage

Access Select's internal state and methods using `SelectConsumer` for programmatic control, conditional rendering, and advanced customization patterns.

## SelectConsumer

SelectConsumer provides access to Select's context via a render prop. Use it to read state or call methods from anywhere inside the Select component.

```tsx
"use client";

import { Select, SelectConsumer, SelectOption } from "@geckoui/geckoui";
import { useState } from "react";

function Example() {
  const [value, setValue] = useState<string | null>(null);

return (
    <Select value={value} onChange={setValue} filterable placeholder="Select a framework...">
      <SelectConsumer
        render={({ open, keyword, options }) => (
          <div className="p-3 border rounded-md bg-gray-50 dark:bg-neutral-800 text-sm mb-2">
            <p>
              <strong>Status:</strong> {open ? "Open" : "Closed"}
            </p>
            <p>
              <strong>Filter:</strong> {keyword || "(none)"}
            </p>
            <p>
              <strong>Total Options:</strong> {options.length}
            </p>
          </div>
        )}
      />
      <SelectOption value="react" label="React" />
      <SelectOption value="vue" label="Vue" />
      <SelectOption value="angular" label="Angular" />
    </Select>
  );
}
```

## Programmatic Control

Control the menu and selection programmatically:

```tsx
<Select value={value} onChange={setValue}>
  <SelectConsumer
    render={({ openMenu, closeMenu, open }) => (
      <div className="flex gap-2 mb-2">
        <Button onClick={openMenu} disabled={open}>
          Open Menu
        </Button>
        <Button onClick={closeMenu} disabled={!open}>
          Close Menu
        </Button>
        <Button
          onClick={() => {
            setValue("python");
            closeMenu();
          }}>
          Select Python
        </Button>
      </div>
    )}
  />
  <SelectOption value="typescript" label="TypeScript" />
  <SelectOption value="javascript" label="JavaScript" />
  <SelectOption value="python" label="Python" />
</Select>
```

## Conditional Rendering

Show/hide UI based on Select state:

```tsx
<Select multiple value={values} onChange={setValues}>
  <SelectConsumer
    render={({ keyword, options, isSelected }) => {
      const selectedCount = options.filter((opt) => isSelected(opt.value)).length;
      const filteredCount = keyword
        ? options.filter((opt) => opt.label.toLowerCase().includes(keyword.toLowerCase())).length
        : options.length;

return (
        <div className="p-2 border-b mb-2 text-sm text-gray-600">
          <div className="flex justify-between">
            <span>Selected: {selectedCount}</span>
            {keyword && <span>Matching: {filteredCount}</span>}
          </div>
        </div>
      );
    }}
  />
  <SelectOption value="bug" label="Bug" />
  <SelectOption value="feature" label="Feature" />
  <SelectOption value="docs" label="Documentation" />
</Select>
```

## Custom Quick Actions

Add quick action buttons inside the dropdown:

```tsx
<Select value={value} onChange={setValue}>
  <SelectConsumer<string>
    render={({ handleChange, closeMenu, value: currentValue }) => (
      <div className="p-2 border-t mt-2 flex gap-2">
        <Button
          size="sm"
          variant="ghost"
          onClick={() => {
            handleChange("active");
            closeMenu();
          }}>
          Quick: Active
        </Button>
        <Button
          size="sm"
          variant="ghost"
          onClick={() => {
            handleChange("inactive");
            closeMenu();
          }}>
          Quick: Inactive
        </Button>
        {currentValue && (
          <Button
            size="sm"
            variant="ghost"
            onClick={() => {
              setValue(null);
              closeMenu();
            }}>
            Clear
          </Button>
        )}
      </div>
    )}
  />
  <SelectOption value="active" label="Active" />
  <SelectOption value="inactive" label="Inactive" />
  <SelectOption value="pending" label="Pending" />
</Select>
```

## Debug View

Inspect Select's internal state during development:

```tsx
<Select multiple value={values} onChange={setValues}>
  <SelectConsumer
    render={({ open, keyword, value, multiple, options, focusedOption }) => (
      <pre className="text-xs bg-gray-50 dark:bg-neutral-800 p-3 rounded border">
        {JSON.stringify(
          {
            open,
            keyword,
            value,
            multiple,
            totalOptions: options.length,
            focusedOption: focusedOption?.label || null
          },
          null,
          2
        )}
      </pre>
    )}
  />
  <SelectOption value="opt1" label="Option 1" />
  <SelectOption value="opt2" label="Option 2" />
</Select>
```

## useSelect Hook

For building completely custom Select components, use the `useSelect` hook directly:

```tsx
import { useSelect } from "@geckoui/geckoui";

function CustomSelectComponent() {
  const {
    open,
    openMenu,
    closeMenu,
    toggleMenu,
    keyword,
    setKeyword,
    value,
    handleChange,
    isSelected,
    options,
    focusedOption,
    setFocusedOption,
    isEmpty,
    floating,
    inputRef,
    setInputRef
  } = useSelect<string>();

// Build your custom UI here
  return <div>{/* Custom implementation */}</div>;
}

// Must be used inside a Select component
<Select value={value} onChange={setValue}>
  <CustomSelectComponent />
</Select>;
```

**Important**: `useSelect` must be called inside a Select component (it uses React Context).

## Available Context Properties

### State

| Property            | Type       | Description                        |
| ------------------- | ---------- | ---------------------------------- |
| `open`              | `boolean`  | Whether dropdown is open           |
| `keyword`           | `string`   | Current filter keyword             |
| `value`             | `T \| T[]` | Current selected value(s)          |
| `multiple`          | `boolean`  | Whether in multiple selection mode |
| `isEmpty`           | `boolean`  | Whether no options match filter    |
| `disabled`          | `boolean`  | Whether Select is disabled         |
| `placeholder`       | `string`   | Placeholder text                   |
| `closeMenuOnSelect` | `boolean`  | Auto-close behavior                |

### Data

| Property        | Type                       | Description              |
| --------------- | -------------------------- | ------------------------ |
| `options`       | `SelectOptionConfig<T>[]`  | All available options    |
| `focusedOption` | `FocusedOption<T> \| null` | Currently focused option |

### Methods

| Method             | Type                                 | Description                 |
| ------------------ | ------------------------------------ | --------------------------- |
| `openMenu`         | `() => void`                         | Open the dropdown           |
| `closeMenu`        | `() => void`                         | Close the dropdown          |
| `toggleMenu`       | `() => void`                         | Toggle dropdown state       |
| `handleChange`     | `(value: T) => void`                 | Select/deselect an option   |
| `isSelected`       | `(value: T) => boolean`              | Check if option is selected |
| `setKeyword`       | `(keyword: string) => void`          | Update filter keyword       |
| `setOpen`          | `(open: boolean) => void`            | Set open state directly     |
| `setFocusedOption` | `(option: FocusedOption<T>) => void` | Set focused option          |

### Advanced

| Property      | Type                          | Description                  |
| ------------- | ----------------------------- | ---------------------------- |
| `floating`    | `UseFloatingReturn`           | Floating UI positioning data |
| `inputRef`    | `RefObject<HTMLInputElement>` | Ref for filter input         |
| `setInputRef` | `(ref: any) => RefCallback`   | Set input ref callback       |
| `prefix`      | `ReactNode`                   | Prefix content               |
| `suffix`      | `ReactNode`                   | Suffix content               |

## When to Use

Use SelectConsumer/useSelect when you need to:

* Build completely custom Select UI
* Access internal state for debugging
* Sync Select state with external systems
* Create conditional rendering based on Select state

## When NOT to Use

Don't use SelectConsumer when:

* SelectTrigger can solve your custom trigger needs
* SelectOption custom content is sufficient
* You just need custom empty states (use SelectEmpty)
* You want basic filtering (use filterable prop)

## Related Pages

* [SelectTrigger](/docs/select/select-trigger) - Custom trigger patterns (simpler than useSelect)
* [SelectOption](/docs/select/select-option) - Custom option content and behavior
* [SelectEmpty](/docs/select/select-empty) - Custom empty states
* [Basic Usage](/docs/select) - Introduction to Select

# Filterable Select

import { Select, SelectOption, SelectDropdownSearch, SelectEmpty } from '@geckoui/geckoui';
import { InlineFilterExample, DropdownFilterExample, FilterableMultipleExample, FilterWithEmptyStateExample, DropdownFilterLargeListExample, CustomFilterContentExample } from '@/components/examples/select/filterable-examples';

# Filterable Select

Add search and filtering capabilities to Select components with two modes: inline filtering (typing in the button) and dropdown filtering (search input in the dropdown menu).

## Inline Filtering

Type directly in the select button to filter options. Best for moderate lists where you want quick filtering without an extra input field.

```tsx
'use client';

import { useState } from 'react';
import { Select, SelectOption } from '@geckoui/geckoui';

function Example() {
  const [value, setValue] = useState<string | null>(null);

return (
    <Select
      filterable="inline"
      value={value}
      onChange={setValue}
      placeholder="Type to filter..."
    >
      <SelectOption value="afghanistan" label="Afghanistan" />
      <SelectOption value="albania" label="Albania" />
      <SelectOption value="algeria" label="Algeria" />
      <SelectOption value="argentina" label="Argentina" />
      <SelectOption value="australia" label="Australia" />
      {/* ... more options */}
    </Select>
  );
}
```

## Dropdown Filtering

Adds a default search input inside the dropdown menu. Best for large lists where you want a dedicated search field.

```tsx
import { Select, SelectOption } from '@geckoui/geckoui';

const [value, setValue] = useState<string | null>(null);

<Select
  filterable="dropdown"
  value={value}
  onChange={setValue}
  placeholder="Select a framework..."
>
  <SelectOption value="react" label="React" />
  <SelectOption value="vue" label="Vue" />
  <SelectOption value="angular" label="Angular" />
  <SelectOption value="svelte" label="Svelte" />
  <SelectOption value="solid" label="Solid" />
</Select>
```

The `filterable="dropdown"` prop automatically adds a default search input at the top of the dropdown.

## Filterable with Multiple Selection

```tsx
const [values, setValues] = useState<string[]>([]);

<Select
  multiple
  filterable="inline"
  value={values}
  onChange={setValues}
  placeholder="Select skills..."
  closeMenuOnSelect={false}
>
  <SelectOption value="typescript" label="TypeScript" />
  <SelectOption value="javascript" label="JavaScript" />
  <SelectOption value="python" label="Python" />
  <SelectOption value="java" label="Java" />
  {/* ... more options */}
</Select>
```

## With Empty State

Use `SelectEmpty` to show a message when no options match the filter:

```tsx
import { Select, SelectOption, SelectEmpty } from '@geckoui/geckoui';

const [value, setValue] = useState<string | null>(null);

<Select
  filterable="dropdown"
  value={value}
  onChange={setValue}
  placeholder="Search products..."
>
  <SelectOption value="laptop" label="Laptop" />
  <SelectOption value="phone" label="Phone" />
  <SelectOption value="tablet" label="Tablet" />
  <SelectEmpty>
    <div className="text-center py-4 text-gray-500">
      <p>No products found</p>
      <p className="text-sm mt-1">Try a different search term</p>
    </div>
  </SelectEmpty>
</Select>
```

## Large Lists with Dropdown Filter

```tsx
const [value, setValue] = useState<string | null>(null);

const colors = [
  'Red', 'Blue', 'Green', 'Yellow', 'Orange', 'Purple', 'Pink', 'Brown',
  'Black', 'White', 'Gray', 'Cyan', 'Magenta', 'Lime', 'Indigo', 'Violet',
  // ... more colors
];

<Select
  filterable="dropdown"
  value={value}
  onChange={setValue}
  placeholder="Pick a color..."
>
  {colors.map((color) => (
    <SelectOption
      key={color}
      value={color.toLowerCase()}
      label={color}
    />
  ))}
  <SelectEmpty>No colors match your search</SelectEmpty>
</Select>
```

## Custom Content with Filtering

The filter searches through the `label` prop. For complex content, include searchable text in the label:

```tsx
const users = [
  { id: 'user1', name: 'John Doe', email: 'john@example.com', role: 'Admin' },
  { id: 'user2', name: 'Jane Smith', email: 'jane@example.com', role: 'Developer' },
  // ... more users
];

<Select
  filterable="dropdown"
  value={value}
  onChange={setValue}
  placeholder="Select a user..."
>
  {users.map((user) => (
    <SelectOption
      key={user.id}
      value={user.id}
      label={`${user.name} ${user.email}`}
    >
      {({ selected, focused }) => (
        <div className="flex items-center justify-between">
          <div>
            <div>{user.name}</div>
            <div className="text-xs text-gray-500">{user.email}</div>
          </div>
          <span className="text-xs bg-gray-100 px-2 py-1 rounded">
            {user.role}
          </span>
        </div>
      )}
    </SelectOption>
  ))}
  <SelectEmpty>No users found</SelectEmpty>
</Select>
```

## Props API

### Select Props

| Prop         | Type                                | Default | Description           |
| ------------ | ----------------------------------- | ------- | --------------------- |
| `filterable` | `boolean \| 'inline' \| 'dropdown'` | `false` | Enable filtering mode |

## Custom Search Input with SelectDropdownSearch

If you want to customize the search input appearance in dropdown mode, you can use the `SelectDropdownSearch` component:

```tsx
import { Select, SelectOption, SelectDropdownSearch } from '@geckoui/geckoui';

<Select filterable="dropdown" value={value} onChange={setValue}>
  <SelectDropdownSearch placeholder="Custom search..." className="border-2" />
  <SelectOption value="opt1" label="Option 1" />
  <SelectOption value="opt2" label="Option 2" />
</Select>
```

### SelectDropdownSearch Props

| Prop          | Type     | Default               | Description                  |
| ------------- | -------- | --------------------- | ---------------------------- |
| `placeholder` | `string` | `"Search options..."` | Placeholder for search input |
| `className`   | `string` | -                     | CSS class for custom styling |

**Note**: `SelectDropdownSearch` is optional. The `filterable="dropdown"` prop provides a default search input automatically.

## Filtering Behavior

### Inline Mode

* Click select → start typing to filter
* Selected value is displayed when menu is closed
* Filter is cleared when menu closes
* Best for: Moderate lists (10-50 items)

### Dropdown Mode

* Click select → menu opens with search input
* Focus automatically moves to search input
* Filter is cleared when menu closes
* Best for: Large lists (50+ items)

### Filter Matching

* Case-insensitive substring matching
* Searches the `label` prop of each SelectOption
* Hidden options (via `show` prop) are excluded from filtering

## Keyboard Navigation

Works the same as non-filterable select:

* **Arrow Up/Down**: Navigate filtered options
* **Enter/Space**: Select focused option
* **Escape**: Clear filter and close menu
* **Tab**: Close menu
* **Type**: Filter options (inline mode)

## Accessibility

* Search input has proper ARIA labels
* Keyboard navigation through filtered results
* Screen reader announces filtered count
* Focus management between search and options

## Related Pages

* [SelectEmpty](/docs/select/select-empty) - Custom empty state messages
* [SelectOption](/docs/select/select-option) - Custom option content
* [Multiple Selection](/docs/select/multiple) - Combine with multi-select
* [SelectTrigger](/docs/select/select-trigger) - Custom filter input

# Select

import {
  BasicSelectExample,
  ClearableSelectExample,
  DisabledOptionsExample,
  DisabledSelectExample,
  PlacementOptionsExample,
  WithPlaceholderExample
} from "@/components/examples/select/basic-examples";
import {
  ComplexGroupingExample,
  GroupedOptionsExample,
  GroupedWithFilterableExample,
  StaticNoteExample,
  WithHeaderAndFooterExample
} from "@/components/examples/select/static-elements-examples";
import { Select, SelectOption } from "@geckoui/geckoui";

# Select

A customizable select dropdown component with support for single and multiple selections, keyboard navigation, search filtering, and custom positioning. Built with floating-ui for intelligent dropdown placement.

## Installation

```tsx
import { Select, SelectOption } from "@geckoui/geckoui";
```

## Basic Usage

```tsx
"use client";

import { Select, SelectOption } from "@geckoui/geckoui";
import { useState } from "react";

function Example() {
  const [value, setValue] = useState<string | null>(null);

return (
    <Select value={value} onChange={setValue}>
      <SelectOption value="react" label="React" />
      <SelectOption value="vue" label="Vue" />
      <SelectOption value="angular" label="Angular" />
    </Select>
  );
}
```

**Important**: Use `null` or `undefined` for no selection. An empty string `""` is considered a valid value and will try to match against options.

## Props API

| Prop                   | Type                                | Default          | Description                                |
| ---------------------- | ----------------------------------- | ---------------- | ------------------------------------------ |
| `value`                | `T \| null`                         | -                | Selected value (required)                  |
| `onChange`             | `(value: T \| null) => void`        | -                | Callback when selection changes (required) |
| `placeholder`          | `string`                            | -                | Placeholder text when empty                |
| `disabled`             | `boolean`                           | `false`          | Disable the select                         |
| `closeMenuOnSelect`    | `boolean`                           | `true`           | Close menu after selection                 |
| `placement`            | `Placement`                         | `'bottom-start'` | Menu placement position                    |
| `floatingStrategy`     | `Strategy`                          | -                | Floating positioning strategy              |
| `wrapperClassName`     | `string`                            | -                | CSS class for wrapper                      |
| `menuClassName`        | `string`                            | -                | CSS class for menu                         |
| `placeholderClassName` | `string`                            | -                | CSS class for placeholder                  |
| `className`            | `string`                            | -                | CSS class for select button                |
| `filterable`           | `boolean \| 'inline' \| 'dropdown'` | `false`          | Enable search filtering                    |
| `multiple`             | `boolean`                           | `false`          | Enable multiple selection                  |
| `hideDefaultEmptyUI`   | `boolean`                           | `false`          | Hide default empty state                   |
| `inputRef`             | `RefObject`                         | -                | Ref for filter input                       |
| `prefix`               | `ReactNode`                         | -                | Content before select button               |
| `suffix`               | `ReactNode`                         | -                | Content after select button                |
| `clearable`            | `boolean`                           | `false`          | Show a clear button to reset the selection |

## Examples

### With Placeholder

```tsx
const [value, setValue] = useState<string | null>(null);

<Select value={value} onChange={setValue} placeholder="Choose a framework...">
  <SelectOption value="next" label="Next.js" />
  <SelectOption value="remix" label="Remix" />
  <SelectOption value="gatsby" label="Gatsby" />
</Select>;
```

### Disabled Options

```tsx
const [value, setValue] = useState<string | null>(null);

<Select value={value} onChange={setValue}>
  <SelectOption value="available" label="Available Option" />
  <SelectOption value="disabled" label="Disabled Option" disabled />
  <SelectOption value="another" label="Another Available" />
</Select>;
```

### Disabled Select

```tsx
<Select value="selected" onChange={() => {}} disabled>
  <SelectOption value="selected" label="Selected Option" />
  <SelectOption value="other" label="Other Option" />
</Select>
```

### Clearable

Enable a clear button to reset the selection by setting `clearable` to `true`.

```tsx
const [value, setValue] = useState<string | null>(null);

<Select value={value} onChange={setValue} clearable placeholder="Select a framework...">
  <SelectOption value="react" label="React" />
  <SelectOption value="vue" label="Vue" />
  <SelectOption value="angular" label="Angular" />
</Select>;
```

### Placement Options

```tsx
const [value, setValue] = useState<string | null>(null);

// Opens upward
<Select value={value} onChange={setValue} placement="top-start">
  <SelectOption value="a" label="Choice A" />
  <SelectOption value="b" label="Choice B" />
</Select>

// Aligns to right
<Select value={value} onChange={setValue} placement="bottom-end">
  <SelectOption value="a" label="Choice A" />
  <SelectOption value="b" label="Choice B" />
</Select>
```

## Grouped Options with Static Elements

You can add any HTML elements inside Select to create headers, dividers, and footers. These static elements won't interfere with filtering or selection.

### Basic Grouping

```tsx
const [value, setValue] = useState<string | null>(null);

<Select value={value} onChange={setValue}>
  <div className="px-3 py-2 text-xs font-semibold text-gray-500 uppercase">Frontend</div>
  <SelectOption value="react" label="React" />
  <SelectOption value="vue" label="Vue" />
  <SelectOption value="angular" label="Angular" />

<div className="px-3 py-2 text-xs font-semibold text-gray-500 uppercase">Backend</div>
  <SelectOption value="node" label="Node.js" />
  <SelectOption value="django" label="Django" />
  <SelectOption value="rails" label="Rails" />
</Select>;
```

### Grouped with Filterable

Static elements remain visible during filtering:

```tsx
<Select filterable="inline" value={value} onChange={setValue}>
  <div className="px-3 py-2 text-xs font-semibold text-gray-500 uppercase bg-gray-50 dark:bg-neutral-800">
    Frontend Frameworks
  </div>
  <SelectOption value="react" label="React" />
  <SelectOption value="vue" label="Vue" />

<div className="px-3 py-2 text-xs font-semibold text-gray-500 uppercase bg-gray-50 dark:bg-neutral-800">
    Backend Frameworks
  </div>
  <SelectOption value="express" label="Express" />
  <SelectOption value="nest" label="NestJS" />
</Select>
```

### With Header and Footer

```tsx
<Select value={value} onChange={setValue}>
  <div className="px-3 py-2 border-b bg-gray-50 dark:bg-neutral-800">
    <p className="text-sm font-medium">Choose your favorite color</p>
    <p className="text-xs text-gray-500">This will be used as your theme</p>
  </div>

<div className="px-3 py-2 border-t bg-gray-50 dark:bg-neutral-800">
    <a href="#" className="text-xs text-blue-600 hover:underline">
      Customize colors →
    </a>
  </div>
</Select>
```

### Complex Grouping

```tsx
<Select value={value} onChange={setValue}>
  <div className="px-3 py-2 bg-blue-50">
    <p className="text-xs font-semibold text-blue-700">⚡ Popular</p>
  </div>
  <SelectOption value="javascript" label="JavaScript" />
  <SelectOption value="python" label="Python" />

<div className="px-3 py-2 bg-green-50 mt-1">
    <p className="text-xs font-semibold text-green-700">🚀 Trending</p>
  </div>
  <SelectOption value="rust" label="Rust" />
  <SelectOption value="go" label="Go" />

<div className="px-3 py-2">
    <p className="text-xs font-semibold text-gray-500">Others</p>
  </div>
  <SelectOption value="java" label="Java" />
  <SelectOption value="csharp" label="C#" />
</Select>
```

### Static Notes

```tsx
<Select value={value} onChange={setValue}>
  <SelectOption value="free" label="Free Plan" />
  <SelectOption value="pro" label="Pro Plan - $29/mo" />
  <SelectOption value="enterprise" label="Enterprise Plan - $99/mo" />

<div className="px-3 py-2 mt-2 bg-yellow-50 border border-yellow-200 rounded mx-2 mb-2">
    <p className="text-xs text-yellow-800">
      💡 <strong>Tip:</strong> Annual billing saves 20%
    </p>
  </div>
</Select>
```

**Key Points**:

* Static HTML elements (divs, hr, etc.) won't interfere with option selection
* They remain visible during filtering
* Useful for headers, dividers, footers, and informational content
* Style them with any CSS classes

## Keyboard Navigation

* **Arrow Up/Down**: Navigate options
* **Enter/Space**: Select focused option
* **Escape**: Close menu
* **Tab**: Close menu and move to next element
* **Type to search**: Filter options (when filterable enabled)

## Accessibility

* Built with floating-ui for intelligent positioning
* Fully keyboard navigable
* Click-outside to close
* Focus management
* Works with screen readers
* ARIA attributes automatically applied

## Styling

The component uses BEM-style class names:

* `GeckoUISelect` - Main container
* `GeckoUISelectButton` - Select button
* `GeckoUISelectMenu` - Menu container
* `GeckoUISelectOption` - Individual option
* `GeckoUISelectOption--selected` - Applied to selected options
* `GeckoUISelectOption--focused` - Applied to focused option

## Related Pages

* [Multiple Selection](/docs/select/multiple) - Multi-select mode with chips
* [Filterable](/docs/select/filterable) - Search and filtering
* [SelectOption](/docs/select/select-option) - Advanced option patterns
* [SelectTrigger](/docs/select/select-trigger) - Custom triggers
* [SelectEmpty](/docs/select/select-empty) - Empty states
* [Advanced](/docs/select/advanced) - Programmatic control

# Multiple Selection

import { Select, SelectOption } from '@geckoui/geckoui';
import { BasicMultipleExample, MultipleWithPlaceholderExample, MultipleWithDefaultValuesExample, MultipleCloseMenuOnSelectExample, MultipleWithClearExample, MultipleCustomContentExample } from '@/components/examples/select/multiple-examples';

# Multiple Selection

Enable multiple selection mode by setting the `multiple` prop. The component will display selected items as chips and allow users to select/deselect multiple options.

## Basic Multiple Selection

```tsx
'use client';

import { useState } from 'react';
import { Select, SelectOption } from '@geckoui/geckoui';

function Example() {
  const [values, setValues] = useState<string[]>([]);

return (
    <Select multiple value={values} onChange={setValues}>
      <SelectOption value="typescript" label="TypeScript" />
      <SelectOption value="javascript" label="JavaScript" />
      <SelectOption value="python" label="Python" />
      <SelectOption value="rust" label="Rust" />
      <SelectOption value="go" label="Go" />
    </Select>
  );
}
```

**Important**: For multiple selection mode, the value must be an array (`string[]`). Use an empty array `[]` for no selection.

## With Placeholder

```tsx
const [values, setValues] = useState<string[]>([]);

<Select
  multiple
  value={values}
  onChange={setValues}
  placeholder="Select programming languages..."
>
  <SelectOption value="typescript" label="TypeScript" />
  <SelectOption value="javascript" label="JavaScript" />
  <SelectOption value="python" label="Python" />
</Select>
```

## With Default Values

```tsx
const [values, setValues] = useState<string[]>(['typescript', 'python']);

<Select multiple value={values} onChange={setValues}>
  <SelectOption value="typescript" label="TypeScript" />
  <SelectOption value="javascript" label="JavaScript" />
  <SelectOption value="python" label="Python" />
  <SelectOption value="rust" label="Rust" />
  <SelectOption value="go" label="Go" />
</Select>
```

## Close Menu on Select

By default, the menu remains open after each selection in multiple mode. You can change this behavior by setting `closeMenuOnSelect` to `true`.

```tsx
const [values, setValues] = useState<string[]>([]);

<Select
  multiple
  value={values}
  onChange={setValues}
  closeMenuOnSelect
  placeholder="Menu stays open..."
>
  <SelectOption value="reading" label="Reading" />
  <SelectOption value="writing" label="Writing" />
  <SelectOption value="coding" label="Coding" />
  <SelectOption value="gaming" label="Gaming" />
</Select>
```

## With Clear Button

```tsx
import { Button } from '@geckoui/geckoui';

const [values, setValues] = useState<string[]>(['react', 'vue']);

<div className="space-y-2">
  <Select multiple value={values} onChange={setValues}>
    <SelectOption value="react" label="React" />
    <SelectOption value="vue" label="Vue" />
    <SelectOption value="angular" label="Angular" />
    <SelectOption value="svelte" label="Svelte" />
  </Select>
  <Button
    variant="outlined"
    size="sm"
    onClick={() => setValues([])}
    disabled={values.length === 0}
  >
    Clear Selection ({values.length})
  </Button>
</div>
```

## Custom Content with Multiple Select

```tsx
const [values, setValues] = useState<string[]>([]);

<Select multiple value={values} onChange={setValues}>
  <SelectOption value="user1" label="John Doe">
    {({ selected, focused }) => (
      <div className="flex items-center gap-2">
        <div className="w-8 h-8 rounded-full bg-blue-500 flex items-center justify-center text-white text-sm">
          JD
        </div>
        <div className={focused ? 'font-semibold' : ''}>
          <div>John Doe</div>
          <div className="text-xs text-gray-500">john@example.com</div>
        </div>
      </div>
    )}
  </SelectOption>
  <SelectOption value="user2" label="Jane Smith">
    {({ selected, focused }) => (
      <div className="flex items-center gap-2">
        <div className="w-8 h-8 rounded-full bg-green-500 flex items-center justify-center text-white text-sm">
          JS
        </div>
        <div className={focused ? 'font-semibold' : ''}>
          <div>Jane Smith</div>
          <div className="text-xs text-gray-500">jane@example.com</div>
        </div>
      </div>
    )}
  </SelectOption>
</Select>
```

## Multiple Selection Props

| Prop                | Type                    | Default | Description                                                      |
| ------------------- | ----------------------- | ------- | ---------------------------------------------------------------- |
| `multiple`          | `boolean`               | `false` | Enable multiple selection mode                                   |
| `value`             | `T[]`                   | -       | Array of selected values (required)                              |
| `onChange`          | `(values: T[]) => void` | -       | Callback when selection changes (required)                       |
| `closeMenuOnSelect` | `boolean`               | `false` | Close menu after each selection (defaults to false for multiple) |

## Behavior

### Selection Toggle

Clicking an option in multiple mode toggles its selection:

* If not selected → adds to array
* If already selected → removes from array

### Chip Display

Selected values are displayed as removable chips in the select button. Click the × icon on a chip to remove that selection.

### Keyboard Navigation

All keyboard shortcuts from single select work in multiple mode:

* **Space/Enter**: Toggle selection of focused option
* **Arrow keys**: Navigate options
* **Escape**: Close menu
* **Tab**: Close menu and move focus

## TypeScript Types

```tsx
interface MultipleSelectProps<T> {
  multiple: true;
  value: T[];
  onChange: (values: T[]) => void;
  // ... other props
}

// Example with string array
const [values, setValues] = useState<string[]>([]);

// Example with number array
const [ids, setIds] = useState<number[]>([]);

// Example with object array
interface User {
  id: number;
  name: string;
}
const [users, setUsers] = useState<User[]>([]);
```

## Related Pages

* [Filterable Select](/docs/select/filterable) - Add search to multiple select
* [SelectOption](/docs/select/select-option) - Advanced option patterns
* [SelectTrigger](/docs/select/select-trigger) - Custom chips display
* [Basic Usage](/docs/select) - Single selection mode

# SelectEmpty

import { Select, SelectOption, SelectEmpty } from '@geckoui/geckoui';
import { BasicEmptyExample, CustomMessageExample, StyledEmptyExample, EmptyWithActionExample, MultipleEmptyStatesExample, EmptyWithImageExample } from '@/components/examples/select/select-empty-examples';

# SelectEmpty

SelectEmpty displays a placeholder message when no options match the search filter. Use it to provide helpful feedback, suggestions, or actions when search returns no results.

## Basic Usage

```tsx
'use client';

import { useState } from 'react';
import { Select, SelectOption, SelectEmpty } from '@geckoui/geckoui';

function Example() {
  const [value, setValue] = useState<string | null>(null);

return (
    <Select filterable="dropdown" value={value} onChange={setValue}>
      <SelectOption value="apple" label="Apple" />
      <SelectOption value="banana" label="Banana" />
      <SelectOption value="cherry" label="Cherry" />
      <SelectEmpty />
    </Select>
  );
}
```

**Default message**: If no children are provided, displays "No options".

## Custom Message

```tsx
<Select filterable="dropdown" value={value} onChange={setValue}>
  <SelectOption value="laptop" label="Laptop" />
  <SelectOption value="phone" label="Phone" />
  <SelectEmpty>
    No products found. Try a different search term.
  </SelectEmpty>
</Select>
```

## Styled Empty State

```tsx
<Select filterable="dropdown" value={value} onChange={setValue}>
  <SelectOption value="react" label="React" />
  <SelectOption value="vue" label="Vue" />
  <SelectEmpty className="text-center py-8 text-gray-500">
    <div className="text-4xl mb-2">🔍</div>
    <p className="font-medium">No frameworks found</p>
    <p className="text-sm mt-1">Try searching for something else</p>
  </SelectEmpty>
</Select>
```

## With Action Button

```tsx
const [showForm, setShowForm] = useState(false);

<Select filterable="dropdown" value={value} onChange={setValue}>
  <SelectOption value="bug" label="Bug" />
  <SelectOption value="feature" label="Feature" />
  <SelectEmpty>
    <div className="text-center py-6">
      <p className="text-gray-600 mb-3">No matching tags found</p>
      <button
        type="button"
        onClick={() => setShowForm(true)}
        className="text-blue-600 hover:text-blue-700 font-medium text-sm"
      >
        + Create new tag
      </button>
    </div>
  </SelectEmpty>
</Select>
```

## Multiple Empty States

Combine SelectEmpty with `show="always"` options for complex layouts:

```tsx
<Select filterable="dropdown" value={value} onChange={setValue}>
  {/* Regular options */}
  <SelectOption value="us" label="United States" />
  <SelectOption value="uk" label="United Kingdom" />
  <SelectOption value="ca" label="Canada" />

{/* Always visible divider */}
  <hr />

{/* Empty state with help text */}
  <SelectEmpty>
    <div className="px-4 py-3 text-sm text-gray-600">
      <p className="font-medium mb-1">Can't find your country?</p>
      <p>Try searching with different spelling or abbreviation</p>
    </div>
  </SelectEmpty>
</Select>
```

## With Icon/Image

```tsx
<Select filterable="dropdown" value={value} onChange={setValue}>
  <SelectOption value="user1" label="John Doe" />
  <SelectOption value="user2" label="Jane Smith" />
  <SelectEmpty>
    <div className="flex flex-col items-center justify-center py-8 px-4">
      <div className="w-16 h-16 bg-gray-100 rounded-full flex items-center justify-center mb-3">
        <svg className="w-8 h-8 text-gray-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M16 7a4 4 0 11-8 0 4 4 0 018 0zM12 14a7 7 0 00-7 7h14a7 7 0 00-7-7z" />
        </svg>
      </div>
      <p className="text-gray-700 font-medium">No users found</p>
      <p className="text-gray-500 text-sm mt-1">Try adjusting your search</p>
    </div>
  </SelectEmpty>
</Select>
```

## Props API

| Prop        | Type        | Default        | Description                |
| ----------- | ----------- | -------------- | -------------------------- |
| `children`  | `ReactNode` | `"No options"` | Custom empty state content |
| `className` | `string`    | -              | CSS class for styling      |

## When It Appears

SelectEmpty only renders when:

1. The Select has `filterable` enabled
2. A search/filter keyword is entered
3. No options match the current filter

It does NOT appear when:

* Select has no options at all (before filtering)
* Filter is empty (no keyword entered)
* hideDefaultEmptyUI is true on Select

## Behavior

### Automatic Visibility

The component automatically shows/hides based on filter results - you don't need to manage its visibility manually.

### With hideDefaultEmptyUI

Use `hideDefaultEmptyUI` on Select to completely remove empty state UI:

```tsx
<Select filterable="dropdown" hideDefaultEmptyUI value={value} onChange={setValue}>
  <SelectDropdownSearch />
  <SelectOption value="a" label="A" />
  <SelectEmpty>This will NOT render</SelectEmpty>
</Select>
```

## Styling

Base CSS class: `GeckoUISelectEmpty`

You can customize with the `className` prop or target the base class in your stylesheet.

## Common Use Cases

### Loading State

```tsx
const [loading, setLoading] = useState(false);

<SelectEmpty>
  {loading ? (
    <div className="text-center py-4">
      <Spinner size="sm" />
      <p className="text-sm text-gray-600 mt-2">Loading...</p>
    </div>
  ) : (
    <p>No results found</p>
  )}
</SelectEmpty>
```

### Create New Item

```tsx
<SelectEmpty>
  <button
    onClick={() => {
      createNewItem(keyword);
      closeMenu();
    }}
  >
    Create "{keyword}"
  </button>
</SelectEmpty>
```

### Help Text with Links

```tsx
<SelectEmpty>
  <div className="px-4 py-3">
    <p className="mb-2">No matches found</p>
    <a href="/help" className="text-blue-600 text-sm">
      Learn about search syntax →
    </a>
  </div>
</SelectEmpty>
```

## Accessibility

* Uses semantic HTML for screen readers
* Properly announces "no results" state
* Maintains keyboard navigation context

## Related Pages

* [Filterable](/docs/select/filterable) - Enable search and filtering
* [SelectOption](/docs/select/select-option) - Visibility control with `show` prop
* [Basic Usage](/docs/select) - Introduction to Select
* [SelectTrigger](/docs/select/select-trigger) - Custom trigger patterns

# SelectOption

import { Select, SelectOption } from '@geckoui/geckoui';
import { BasicOptionExample, CustomContentExample, HideCheckIconExample, DisabledOptionExample, CustomClickExample, PreventDefaultExample, VisibilityControlExample, ComplexContentExample } from '@/components/examples/select/select-option-examples';

# SelectOption

The SelectOption component represents an individual selectable item within a Select dropdown. It supports custom content rendering, click handlers with preventDefault, visibility control, and automatic keyboard/focus management.

## Basic Usage

```tsx
'use client';

import { useState } from 'react';
import { Select, SelectOption } from '@geckoui/geckoui';

function Example() {
  const [value, setValue] = useState<string | null>(null);

## Custom Content with Render Props

Use a render function to customize the option display based on its state:

```tsx
const [value, setValue] = useState<string | null>(null);

<Select value={value} onChange={setValue}>
  <SelectOption value="user1" label="John Doe">
    {({ selected, focused }) => (
      <div className="flex items-center gap-3">
        <div className="w-10 h-10 rounded-full bg-blue-500 flex items-center justify-center text-white font-semibold">
          JD
        </div>
        <div className={focused ? 'font-semibold' : ''}>
          <div className="font-medium">John Doe</div>
          <div className="text-sm text-gray-500">john@example.com</div>
        </div>
        {selected && <span className="ml-auto text-blue-500">✓</span>}
      </div>
    )}
  </SelectOption>
  {/* ... more options */}
</Select>
```

**Note**: The `label` prop is still required for filtering and accessibility, even when using custom content.

## Hide Check Icon

Remove the default check icon for selected items:

```tsx
<Select value={value} onChange={setValue}>
  <SelectOption value="opt1" label="Option 1" hideCheckIcon />
  <SelectOption value="opt2" label="Option 2" hideCheckIcon />
  <SelectOption value="opt3" label="Option 3" hideCheckIcon />
</Select>
```

## Disabled Options

```tsx
<Select value={value} onChange={setValue}>
  <SelectOption value="free" label="Free Plan" />
  <SelectOption value="pro" label="Pro Plan" disabled />
  <SelectOption value="enterprise" label="Enterprise Plan" disabled />
</Select>
```

## Custom Click Handler

Add custom logic that runs when an option is clicked. The default selection behavior still occurs:

```tsx
const [clickCount, setClickCount] = useState(0);

<SelectOption
  value="custom"
  label="Custom Action"
  onClick={({ selectCurrentOption, closeMenu }) => {
    setClickCount((prev) => prev + 1);
    console.log('Custom action triggered!');
    selectCurrentOption(); // Still selects the option
    closeMenu(); // Closes the menu
  }}
/>
```

### onClick Parameters

The onClick handler receives an object with:

* `selectCurrentOption()` - Function to manually trigger selection
* `closeMenu()` - Function to close the dropdown
* `value` - The option's value
* `preventDefault()` - Function to prevent default selection behavior

## Using preventDefault

Completely override the default selection behavior:

```tsx
<SelectOption
  value="delete"
  label="Delete Item"
  onClick={({ preventDefault, selectCurrentOption, closeMenu }) => {
    preventDefault(); // Prevents automatic selection

if (window.confirm('Are you sure?')) {
      // Custom logic here
      selectCurrentOption(); // Manually select only if confirmed
      closeMenu();
    }
    // If canceled, nothing happens - option is NOT selected
  }}
/>
```

### Common preventDefault Use Cases

```tsx
// Conditional selection based on user permissions
<SelectOption
  value="premium"
  label="Premium Feature"
  onClick={({ preventDefault, selectCurrentOption }) => {
    preventDefault();

if (userHasPremium) {
      selectCurrentOption();
    } else {
      openUpgradeModal();
    }
  }}
/>

// Trigger external action without selection
<SelectOption
  value="export"
  label="Export Data"
  onClick={({ preventDefault, closeMenu }) => {
    preventDefault();
    handleExport();
    closeMenu();
  }}
/>

// Navigate instead of selecting
<SelectOption
  value="settings"
  label="Go to Settings"
  onClick={({ preventDefault, closeMenu }) => {
    preventDefault();
    router.push('/settings');
    closeMenu();
  }}
/>
```

## Visibility Control

Control when options appear using the `show` prop:

```tsx
<Select value={value} onChange={setValue}>
  <SelectOption value="draft" label="Draft" visibility="default" />
  <SelectOption value="published" label="Published" visibility="default" />
  <SelectOption value="archived" label="Archived" visibility="default" />

{/* Always visible, even when filtering */}
  <SelectOption value="admin-only" label="Admin Only Status" visibility="always" />
</Select>
```

### Visibility Modes

* `"default"` - Normal visibility, hidden when filtered out
* `"always"` - Always visible, even during search/filter
* `"empty"` - Only visible when no other options match filter
* `"filtered-and-empty"` - Visible when filtered or empty

## Complex Content Example

```tsx
const frameworks = [
  {
    id: 'react',
    name: 'React',
    description: 'A JavaScript library for building user interfaces',
    popularity: 'Very High',
    color: 'bg-blue-500'
  },
  // ... more frameworks
];

<Select value={value} onChange={setValue}>
  {frameworks.map((framework) => (
    <SelectOption key={framework.id} value={framework.id} label={framework.name}>
      {({ selected, focused }) => (
        <div className="py-1">
          <div className="flex items-center gap-2">
            <div className={`w-3 h-3 rounded-full ${framework.color}`} />
            <span className={focused ? 'font-semibold' : 'font-medium'}>
              {framework.name}
            </span>
            <span className="ml-auto text-xs bg-gray-100 px-2 py-0.5 rounded">
              {framework.popularity}
            </span>
          </div>
          <p className="text-sm text-gray-500 mt-1 ml-5">
            {framework.description}
          </p>
        </div>
      )}
    </SelectOption>
  ))}
</Select>
```

## Props API

| Prop            | Type                                                       | Default     | Description                              |
| --------------- | ---------------------------------------------------------- | ----------- | ---------------------------------------- |
| `value`         | `T`                                                        | -           | Option value (required)                  |
| `label`         | `string`                                                   | -           | Display label and search text (required) |
| `children`      | `ReactNode \| (args) => ReactNode`                         | -           | Custom content or render function        |
| `disabled`      | `boolean`                                                  | `false`     | Disable the option                       |
| `hideCheckIcon` | `boolean`                                                  | `false`     | Hide check icon for selected state       |
| `visibility`    | `'default' \| 'always' \| 'empty' \| 'filtered-and-empty'` | `'default'` | Visibility control                       |
| `onClick`       | `(args) => void`                                           | -           | Custom click handler                     |
| `className`     | `string`                                                   | -           | CSS class for option                     |

### Render Function Arguments

When using a render function as children:

```tsx
{({ selected, focused }) => ReactNode}
```

* `selected` - Boolean indicating if this option is selected
* `focused` - Boolean indicating if this option has keyboard/mouse focus

### onClick Handler Arguments

```tsx
onClick={({ selectCurrentOption, closeMenu, value, preventDefault }) => void}
```

* `selectCurrentOption()` - Manually trigger selection
* `closeMenu()` - Close the dropdown
* `value` - The option's value
* `preventDefault()` - Prevent default selection behavior

## Styling

The component uses BEM-style class names:

* `GeckoUISelectOption` - Base option element
* `GeckoUISelectOption--selected` - Applied when selected
* `GeckoUISelectOption--focused` - Applied when focused
* `GeckoUISelectOption--disabled` - Applied when disabled

## Best Practices

1. **Always provide label**: Even with custom content, the `label` prop is required for filtering and accessibility
2. **Use preventDefault wisely**: Only use when you need complete control over selection behavior
3. **Keep custom content accessible**: Ensure custom content works with keyboard navigation
4. **Consider performance**: For large lists with complex custom content, consider virtualization

## Related Pages

* [Basic Usage](/docs/select) - Introduction to Select
* [Filterable](/docs/select/filterable) - How filtering works with custom content
* [SelectTrigger](/docs/select/select-trigger) - Custom trigger components
* [Multiple Selection](/docs/select/multiple) - Multi-select with custom options

# SelectTrigger

import { Select, SelectOption, SelectTrigger, Input, Button } from '@geckoui/geckoui';
import { BasicTriggerExample, ChipsWithRemoveExample, SingleSelectTriggerExample, CustomStyledChipsExample, TriggerWithClearAllExample } from '@/components/examples/select/select-trigger-examples';

# SelectTrigger

SelectTrigger is a render prop component that gives you complete control over the select button/trigger appearance. Build custom search inputs, chip displays, and complex multi-select interfaces.

## Basic Custom Trigger

Replace the default select button with a custom input and chip display:

```tsx
'use client';

import { useState } from 'react';
import { Select, SelectOption, SelectTrigger, Input } from '@geckoui/geckoui';

function Example() {
  const [values, setValues] = useState<number[]>([]);

return (
    <Select multiple value={values} onChange={setValues}>
      <SelectTrigger<number> multiple>
        {({
          keyword,
          selectedOptions,
          handleInputChange,
          handleKeyboardInteraction,
          openMenu
        }) => (
          <div>
            <Input
              placeholder="Search months..."
              value={keyword}
              onChange={handleInputChange}
              onKeyDown={handleKeyboardInteraction}
              onFocus={openMenu}
              autoComplete="off"
              autoCapitalize="off"
              autoCorrect="off"
              spellCheck={false}
            />
            {selectedOptions.length > 0 && (
              <div className="mt-2 flex flex-wrap gap-2">
                {selectedOptions.map((option) => (
                  <span
                    key={option.value}
                    className="bg-blue-100 text-blue-800 px-2 py-1 rounded text-sm"
                  >
                    {option.label}
                  </span>
                ))}
              </div>
            )}
          </div>
        )}
      </SelectTrigger>
      {Array.from({ length: 12 }, (_, i) => (
        <SelectOption
          key={i}
          value={i}
          label={new Date(0, i).toLocaleString('default', { month: 'long' })}
        />
      ))}
    </Select>
  );
}
```

## Chips with Remove Buttons

Add remove buttons to each chip:

```tsx
import { X } from 'lucide-react';

<Select multiple value={values} onChange={setValues}>
  <SelectTrigger<number> multiple>
    {({
      keyword,
      selectedOptions,
      handleChange,
      handleInputChange,
      handleKeyboardInteraction,
      openMenu
    }) => (
      <div>
        <Input
          placeholder="Type to search..."
          value={keyword}
          onChange={handleInputChange}
          onKeyDown={handleKeyboardInteraction}
          onFocus={openMenu}
          autoComplete="off"
        />
        {selectedOptions.length > 0 && (
          <div className="mt-2 flex flex-wrap gap-2">
            {selectedOptions.map((option) => (
              <span
                key={option.value}
                className="inline-flex items-center gap-1 bg-purple-100 text-purple-800 px-2 py-1 rounded"
              >
                {option.label}
                <button
                  type="button"
                  onClick={(e) => {
                    e.stopPropagation();
                    handleChange(option.value);
                  }}
                  className="hover:bg-purple-200 rounded-full p-0.5"
                >
                  <X className="w-3 h-3" />
                </button>
              </span>
            ))}
          </div>
        )}
      </div>
    )}
  </SelectTrigger>
  <SelectOption value="react" label="React" />
  <SelectOption value="vue" label="Vue" />
  <SelectOption value="angular" label="Angular" />
</Select>
```

## Single Select with Custom Trigger

Use SelectTrigger for single selection mode:

```tsx
const [value, setValue] = useState<string | null>(null);

<Select value={value} onChange={setValue}>
  <SelectTrigger>
    {({
      keyword,
      selectedOptions,
      handleInputChange,
      handleKeyboardInteraction,
      openMenu
    }) => (
      <div className="space-y-2">
        <Input
          placeholder="Search frameworks..."
          value={keyword}
          onChange={handleInputChange}
          onKeyDown={handleKeyboardInteraction}
          onFocus={openMenu}
          autoComplete="off"
        />
        {selectedOptions && (
          <div className="p-2 bg-green-50 border border-green-200 rounded">
            <span className="text-sm text-green-800">
              Selected: <strong>{selectedOptions.label}</strong>
            </span>
          </div>
        )}
      </div>
    )}
  </SelectTrigger>
  <SelectOption value="next" label="Next.js" />
  <SelectOption value="remix" label="Remix" />
</Select>
```

**Note**: For single select, `selectedOptions` is a single object, not an array.

## Custom Styled Chips

Use Button components for chips:

```tsx
import { Button } from '@geckoui/geckoui';

<Select multiple value={values} onChange={setValues}>
  <SelectTrigger<number> multiple>
    {({ selectedOptions, handleChange, /* ... */ }) => (
      <div className="space-y-3">
        <Input placeholder="Select programming languages..." />
        {selectedOptions.length > 0 && (
          <div>
            <div className="text-xs text-gray-500 mb-2">
              {selectedOptions.length} selected
            </div>
            <div className="flex flex-wrap gap-2">
              {selectedOptions.map((option) => (
                <Button
                  key={option.value}
                  type="button"
                  variant="outlined"
                  size="sm"
                  onClick={(e) => {
                    e.stopPropagation();
                    handleChange(option.value);
                  }}
                  className="gap-2"
                >
                  <span>{option.label}</span>
                  <X className="w-3 h-3" />
                </Button>
              ))}
            </div>
          </div>
        )}
      </div>
    )}
  </SelectTrigger>
  {/* ... options */}
</Select>
```

## Props API

| Prop       | Type                  | Description                             |
| ---------- | --------------------- | --------------------------------------- |
| `multiple` | `boolean`             | Must match the Select's `multiple` prop |
| `children` | `(args) => ReactNode` | Render function receiving trigger state |

## Render Function Arguments

### For Multiple Select (`multiple={true}`)

```tsx
{
  keyword: string;
  selectedOptions: Array<{ label: string; value: T }>;
  handleChange: (value: T) => void;
  options: Array<{ label: string; value: T; /* ... */ }>;
  toggleMenu: () => void;
  open: boolean;
  openMenu: () => void;
  closeMenu: () => void;
  hasValue: boolean;
  filteredOptions: Array<{ label: string; value: T; /* ... */ }>;
  handleInputChange: (e: ChangeEvent<HTMLInputElement>) => void;
  handleKeyboardInteraction: (e: KeyboardEvent<HTMLInputElement>) => void;
}
```

### For Single Select (`multiple={false}` or omitted)

```tsx
{
  keyword: string;
  selectedOptions: { label: string; value: T } | null;
  handleChange: (value: T) => void;
  // ... same as multiple
}
```

**Key difference**: `selectedOptions` is an array for multiple select, but a single object (or null) for single select.

### Keyboard Navigation

The `handleKeyboardInteraction` function handles:

* **Arrow Up/Down**: Navigate options
* **Enter**: Select focused option.
* **Tab**: Navigate options.
* **Escape**: Close menu (handled by Select)

Always attach it to your input:

```tsx
<Input
  onKeyDown={handleKeyboardInteraction}
  // ... other props
/>
```

## Best Practices

1. **Always include `autoComplete="off"`** on custom inputs to prevent browser suggestions
2. **Use `e.stopPropagation()`** on chip remove buttons to prevent menu toggling
3. **Match `multiple` prop** on SelectTrigger with Select's `multiple` prop
4. **Handle both keyboard and mouse** interactions for accessibility
5. **Show visual feedback** for selected items and focus states

## Related Pages

* [Multiple Selection](/docs/select/multiple) - Multi-select patterns
* [Filterable](/docs/select/filterable) - Built-in search without custom trigger
* [SelectOption](/docs/select/select-option) - Customize option display
* [Advanced](/docs/select/advanced) - Programmatic control with useSelect hook

Welcome!

Edit Profile

Important Notice

Edit Item

Drawer Content

Filters

Notifications

Quick Actions

Settings