# Sidebar (/docs/blocks/sidebar)



# Sidebar [#sidebar]

The `Sidebar` is a complete navigation block component designed in the style of Apple Music and Podcasts. It features collapsible groups, custom item selections, active/hover styles, glassmorphic layout options, profile/branding sections, and a responsive toggle to collapse to an icon-only view.

## Preview [#preview]

<BlockPreview previewUrl="/preview/sidebar" title="Sidebar Preview" description="Experience the complete responsive layout component with live controls and collapsible navigation states." />

***

## Import [#import]

```tsx
import {
  Sidebar,
  SidebarAside,
  SidebarMain,
  SidebarHeader,
  SidebarGroup,
  SidebarItem,
  SidebarFooter,
  SidebarDivider,
} from '@moul-dev/ui';
```

***

## Layout Structure [#layout-structure]

The Sidebar is built as a set of compound components for complete flexibility:

```tsx
<Sidebar selectedKey={activeKey} onSelectionChange={setActiveKey}>
  <SidebarAside>
    <SidebarHeader>
      {/* Branding, search bar or logo */}
    </SidebarHeader>

    <SidebarGroup title="Group Name">
      <SidebarItem id="home" icon={<HomeIcon />}>Home</SidebarItem>
      <SidebarItem id="settings" icon={<SettingsIcon />}>Settings</SidebarItem>
    </SidebarGroup>

    <SidebarDivider />

    <SidebarFooter>
      {/* Account profile, user email, logout */}
    </SidebarFooter>
  </SidebarAside>

  <SidebarMain>
    {/* Main dashboard or route content */}
  </SidebarMain>
</Sidebar>
```

***

## Features [#features]

### Collapsible Groups [#collapsible-groups]

Wrapping navigation links in `SidebarGroup` automatically supports group collapsibility. When `collapsible` is enabled, clicking the group title toggles item visibility with a smooth grid-based transition.

### Icon-Only Collapse Mode [#icon-only-collapse-mode]

Setting the `isCollapsed` prop shrinks the sidebar to a slim icon-only strip. When collapsed:

* Text labels in `SidebarItem` are hidden.
* Hovering over a collapsed item displays a premium `Tooltip` showing the item's label.
* Group headers and sub-content are collapsed/hidden.

### Styling Variants [#styling-variants]

Supports both `solid` (flat background) and `glass` (glassmorphic translucent backdrop filter) modes out of the box using the `variant` prop.

***

## API Reference [#api-reference]

### Sidebar Props [#sidebar-props]

| Prop                 | Type                           | Default   | Description                                                         |
| :------------------- | :----------------------------- | :-------- | :------------------------------------------------------------------ |
| `isCollapsed`        | `boolean`                      | `false`   | Controlled state for whether the sidebar is collapsed to icon-only. |
| `defaultCollapsed`   | `boolean`                      | `false`   | Uncontrolled default state for the collapse layout.                 |
| `onCollapseChange`   | `(collapsed: boolean) => void` | —         | Callback triggered when the collapse state changes.                 |
| `selectedKey`        | `string`                       | —         | The active/selected item ID (controlled).                           |
| `defaultSelectedKey` | `string`                       | —         | The initial active item ID (uncontrolled).                          |
| `onSelectionChange`  | `(key: string) => void`        | —         | Callback triggered when a new item is selected.                     |
| `variant`            | `'solid' \| 'glass'`           | `'solid'` | Aesthetic variant of the sidebar background.                        |

### SidebarAside Props [#sidebaraside-props]

| Prop                 | Type      | Default | Description                                                    |
| :------------------- | :-------- | :------ | :------------------------------------------------------------- |
| `showCollapseToggle` | `boolean` | `true`  | Renders a built-in floating chevron toggle at the bottom edge. |

### SidebarMain Props [#sidebarmain-props]

Accepts standard JSX children and compile-time StyleX layout overrides via the `style` prop.

### SidebarGroup Props [#sidebargroup-props]

| Prop               | Type                          | Default | Description                                            |
| :----------------- | :---------------------------- | :------ | :----------------------------------------------------- |
| `title`            | `string`                      | —       | The label text displayed at the top of the group.      |
| `collapsible`      | `boolean`                     | `true`  | Whether the group can be expanded/collapsed.           |
| `defaultExpanded`  | `boolean`                     | `true`  | The initial expansion state of the group.              |
| `isExpanded`       | `boolean`                     | —       | Controlled expansion state.                            |
| `onExpandedChange` | `(expanded: boolean) => void` | —       | Callback triggered when group expansion state toggles. |

### SidebarItem Props [#sidebaritem-props]

| Prop         | Type        | Default | Description                                                          |
| :----------- | :---------- | :------ | :------------------------------------------------------------------- |
| `id`         | `string`    | —       | Unique key representing the item (used for selection modeling).      |
| `href`       | `string`    | —       | Render as a link using React Aria's Link capabilities.               |
| `icon`       | `ReactNode` | —       | The SVG or custom react component rendered on the left of the label. |
| `isSelected` | `boolean`   | —       | Manual override to mark the item as selected.                        |

### SidebarFooter Props [#sidebarfooter-props]

| Prop         | Type      | Default | Description                                                   |
| :----------- | :-------- | :------ | :------------------------------------------------------------ |
| `showBorder` | `boolean` | `true`  | Whether to display a divider border above the footer content. |


# Alert (/docs/components/alert)





# Alert [#alert]

## Preview [#preview]

<ComponentPlayground component="Alert" />

The `Alert` component is built with React Aria and styled using StyleX. It supports multiple status variants, inline action buttons, close triggers, and rich custom layout slots.

## Import [#import]

```tsx
import { Alert } from '@moul-dev/ui';
```

## Variants [#variants]

You can customize the type of alert using the `variant` prop:

<ComponentPreview>
  <div className="flex flex-col gap-4 w-full max-w-2xl">
    <Alert variant="info" title="Info Alert" description="This is a standard information notification." />

    <Alert variant="accent" title="Accent Alert" description="This is an accented information notification with a colored icon/title." />

    <Alert variant="success" title="Success Alert" description="The operation completed successfully." />

    <Alert variant="warning" title="Warning Alert" description="This action might affect your configuration settings." />

    <Alert variant="error" title="Error Alert" description="We encountered an issue connecting to the server." />

    <Alert variant="loading" title="Processing your request" description="Please wait while we perform the action." />
  </div>
</ComponentPreview>

```tsx
<Alert variant="info" title="..." description="..." />
<Alert variant="accent" title="..." description="..." />
<Alert variant="success" title="..." description="..." />
<Alert variant="warning" title="..." description="..." />
<Alert variant="error" title="..." description="..." />
<Alert variant="loading" title="..." description="..." />
```

## Actions and Closable [#actions-and-closable]

Alerts can accept an optional inline action element or a close button using `action` and `onClose` props:

<ComponentPreview>
  <div className="flex flex-col gap-4 w-full max-w-2xl">
    <Alert variant="accent" title="Update available" description="A new version is ready to install." action="<Button variant=&#x22;primary&#x22; size=&#x22;sm&#x22;>Refresh</Button>" />

    <AlertDemo />
  </div>
</ComponentPreview>

```tsx
<Alert
  variant="accent"
  title="Update available"
  description="A new version is ready to install."
  action={<Button variant="primary" size="sm">Refresh</Button>}
/>

<Alert
  variant="success"
  title="Profile updated successfully"
  onClose={() => handleClose()}
/>
```

## Rich Content (Children) [#rich-content-children]

You can pass custom children inside the `Alert` component to display nested lists, custom spacing, or elements:

<ComponentPreview>
  <div className="flex flex-col gap-4 w-full max-w-2xl">
    <Alert variant="error" title="Unable to connect to server" action="<Button variant=&#x22;danger&#x22; size=&#x22;sm&#x22;>Retry</Button>">
      <div style="{ marginTop: '8px', fontSize: '14px', color: 'var(--colorFgSubtle)' }">
        <p style="{ margin: '0 0 8px 0' }">
          We're experiencing connection issues. Please try the following:
        </p>

        <ul style="{ listStyleType: 'disc', paddingLeft: '20px', margin: '0', display: 'flex', flexDirection: 'column', gap: '4px' }">
          <li>
            Check your internet connection
          </li>

          <li>
            Refresh the page
          </li>

          <li>
            Clear your browser cache
          </li>
        </ul>
      </div>
    </Alert>
  </div>
</ComponentPreview>

```tsx
import * as stylex from '@stylexjs/stylex';
import { Alert, Button, tokens } from '@moul-dev/ui';

const alertStyles = stylex.create({
  container: {
    marginTop: tokens.spacing2,
    color: tokens.colorFgSubtle,
  },
  paragraph: {
    margin: 0,
    marginBottom: tokens.spacing1,
  },
  list: {
    listStyleType: 'disc',
    paddingInlineStart: tokens.spacing2,
    margin: 0,
    display: 'flex',
    flexDirection: 'column',
  },
});

export default function Example() {
  return (
    <Alert
      variant="error"
      title="Unable to connect to server"
      action={<Button variant="danger" size="sm">Retry</Button>}
    >
      <div {...stylex.props(alertStyles.container)}>
        <p {...stylex.props(alertStyles.paragraph)}>
          We're experiencing connection issues. Please try the following:
        </p>
        <ul {...stylex.props(alertStyles.list)}>
          <li>Check your internet connection</li>
          <li>Refresh the page</li>
          <li>Clear your browser cache</li>
        </ul>
      </div>
    </Alert>
  );
}
```


# AlertDialog (/docs/components/alertdialog)





# AlertDialog [#alertdialog]

## Preview [#preview]

<ComponentPreview>
  <AlertDialogDemo />
</ComponentPreview>

The `AlertDialog` component is built with React Aria and styled using StyleX.

## Import [#import]

```tsx
import { AlertDialog } from '@moul-dev/ui';
```

## Usage [#usage]

Here is a basic example of how to use the `AlertDialog` component:

```tsx
import {
  AlertDialog,
  AlertDialogHeader,
  AlertDialogBody,
  AlertDialogFooter,
  Button
} from '@moul-dev/ui';

export default function Example() {
  return (
    <AlertDialog>
      <AlertDialogHeader>Deactivate Account</AlertDialogHeader>
      <AlertDialogBody>
        Are you sure you want to deactivate your account? This action cannot be undone.
      </AlertDialogBody>
      <AlertDialogFooter>
        <Button variant="outline" onPress={() => {}}>Cancel</Button>
        <Button variant="danger" onPress={() => {}}>Confirm</Button>
      </AlertDialogFooter>
    </AlertDialog>
  );
}
```

## Props [#props]

### AlertDialog Props [#alertdialog-props]

<TypeTable
  type="{
  'role': {
    type: &#x22;'dialog' | 'alertdialog'&#x22;,
    default: &#x22;'alertdialog'&#x22;,
    description: &#x22;The accessibility role matching the content dialog behavior.&#x22;,
  },
}"
/>

<Accordions>
  <Accordion title="Styling">
    <TypeTable
      type="{
          'className': {
            type: &#x22;string&#x22;,
            description: &#x22;The CSS className.&#x22;,
          },
        }"
    />
  </Accordion>
</Accordions>

Default className: `react-aria-Dialog`


# Avatar (/docs/components/avatar)





# Avatar [#avatar]

## Preview [#preview]

<ComponentPreview>
  <div className="flex gap-4">
    <Avatar src="https://github.com/thasophearak.png" alt="Phearak S. Tha" />

    <Avatar src="https://github.com/moul-dev.png" alt="moul.dev" />
  </div>
</ComponentPreview>

The `Avatar` component is built with React Aria and styled using StyleX.

## Import [#import]

```tsx
import { Avatar } from '@moul-dev/ui';
```

## Usage [#usage]

Here is a basic example of how to use the `Avatar` component:

```tsx
import { Avatar } from '@moul-dev/ui';

export default function Example() {
  return (
    <Avatar>
      {/* Component content */}
    </Avatar>
  );
}
```


# Badge (/docs/components/badge)





# Badge [#badge]

## Preview [#preview]

<ComponentPlayground component="Badge" />

The `Badge` component is built with React Aria and styled using StyleX.

## Import [#import]

```tsx
import { Badge } from '@moul-dev/ui';
```

## Usage [#usage]

Here is a basic example of how to use the `Badge` component:

```tsx
import { Badge } from '@moul-dev/ui';

export default function Example() {
  return (
    <Badge>
      {/* Component content */}
    </Badge>
  );
}
```


# Breadcrumbs (/docs/components/breadcrumbs)





# Breadcrumbs [#breadcrumbs]

## Preview [#preview]

<ComponentPreview>
  <Breadcrumbs>
    <BreadcrumbItem>
      Home
    </BreadcrumbItem>

    <BreadcrumbItem>
      Components
    </BreadcrumbItem>

    <BreadcrumbItem>
      Breadcrumbs
    </BreadcrumbItem>
  </Breadcrumbs>
</ComponentPreview>

The `Breadcrumbs` component is built with React Aria and styled using StyleX.

## Import [#import]

```tsx
import { Breadcrumbs } from '@moul-dev/ui';
```

## Usage [#usage]

Here is a basic example of how to use the `Breadcrumbs` component:

```tsx
import { Breadcrumbs } from '@moul-dev/ui';

export default function Example() {
  return (
    <Breadcrumbs>
      {/* Component content */}
    </Breadcrumbs>
  );
}
```

## Props [#props]

### Breadcrumbs Props [#breadcrumbs-props]

<TypeTable
  type="{
  'isDisabled': {
    type: &#x22;boolean&#x22;,
    default: &#x22;false&#x22;,
    description: &#x22;Whether navigation within the breadcrumbs is disabled.&#x22;,
  },
}"
/>

<Accordions>
  <Accordion title="Styling">
    <TypeTable
      type="{
          'className': {
            type: &#x22;string&#x22;,
            description: &#x22;The CSS className.&#x22;,
          },
        }"
    />
  </Accordion>
</Accordions>

Default className: `react-aria-Breadcrumbs`


# Button (/docs/components/button)





# Button [#button]

## Preview [#preview]

<ComponentPlayground component="Button" />

The `Button` component is built with React Aria and styled using StyleX.

## Variants [#variants]

You can customize the appearance of the button using the `variant` prop:

<ComponentPreview>
  <div className="flex flex-wrap gap-3 items-center">
    <Button variant="primary">
      Primary
    </Button>

    <Button variant="secondary">
      Secondary
    </Button>

    <Button variant="tertiary">
      Tertiary
    </Button>

    <Button variant="outline">
      Outline
    </Button>

    <Button variant="ghost">
      Ghost
    </Button>

    <Button variant="danger">
      Danger
    </Button>

    <Button variant="danger-soft">
      Danger Soft
    </Button>
  </div>
</ComponentPreview>

```tsx
<Button variant="primary">Primary</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="tertiary">Tertiary</Button>
<Button variant="outline">Outline</Button>
<Button variant="ghost">Ghost</Button>
<Button variant="danger">Danger</Button>
<Button variant="danger-soft">Danger Soft</Button>
```

## Sizes [#sizes]

You can customize the size of the button using the `size` prop:

<ComponentPreview>
  <div className="flex gap-4 items-center">
    <Button size="sm">
      Small
    </Button>

    <Button size="md">
      Medium (Default)
    </Button>

    <Button size="lg">
      Large
    </Button>
  </div>
</ComponentPreview>

```tsx
<Button size="sm">Small</Button>
<Button size="md">Medium (Default)</Button>
<Button size="lg">Large</Button>
```

## Import [#import]

```tsx
import { Button } from '@moul-dev/ui';
```

## Usage [#usage]

Here is a basic example of how to use the `Button` component:

```tsx
import { Button } from '@moul-dev/ui';

export default function Example() {
  return (
    <Button>
      {/* Component content */}
    </Button>
  );
}
```

## Props [#props]

### Button Props [#button-props]

<TypeTable
  type="{
  'variant': {
    type: &#x22;'primary' | 'secondary' | 'tertiary' | 'outline' | 'ghost' | 'danger' | 'danger-soft'&#x22;,
    default: &#x22;'primary'&#x22;,
    description: &#x22;The visual style variant of the button.&#x22;,
  },
  'size': {
    type: &#x22;'sm' | 'md' | 'lg'&#x22;,
    default: &#x22;'md'&#x22;,
    description: &#x22;The size of the button.&#x22;,
  },
  'isDisabled': {
    type: &#x22;boolean&#x22;,
    default: &#x22;false&#x22;,
    description: &#x22;Whether the button is disabled.&#x22;,
  },
  'isPending': {
    type: &#x22;boolean&#x22;,
    default: &#x22;false&#x22;,
    description: &#x22;Whether the button is in a pending state, showing a progress spinner and disabling interactions.&#x22;,
  },
  'href': {
    type: &#x22;string&#x22;,
    description: &#x22;A URL to link to. Renders the button as an anchor link.&#x22;,
  },
  'target': {
    type: &#x22;string&#x22;,
    description: &#x22;The target attribute for the link (e.g. '_blank'). Only used when href is set.&#x22;,
  },
  'rel': {
    type: &#x22;string&#x22;,
    description: &#x22;The rel attribute for the link. Only used when href is set.&#x22;,
  },
}"
/>

<Accordions>
  <Accordion title="Events">
    <TypeTable
      type="{
          'onPress': {
            type: &#x22;(e: PressEvent) => void&#x22;,
            description: &#x22;Handler that is called when the press is released over the target.&#x22;,
          },
          'onPressStart': {
            type: &#x22;(e: PressEvent) => void&#x22;,
            description: &#x22;Handler that is called when a press interaction starts.&#x22;,
          },
          'onPressEnd': {
            type: &#x22;(e: PressEvent) => void&#x22;,
            description: &#x22;Handler that is called when a press interaction ends.&#x22;,
          },
          'onPressChange': {
            type: &#x22;(isPressed: boolean) => void&#x22;,
            description: &#x22;Handler that is called when the press state changes.&#x22;,
          },
          'onPressUp': {
            type: &#x22;(e: PressEvent) => void&#x22;,
            description: &#x22;Handler that is called when a press is released over the target, regardless of where it started.&#x22;,
          },
          'onHoverStart': {
            type: &#x22;(e: HoverEvent) => void&#x22;,
            description: &#x22;Handler that is called when a hover interaction starts.&#x22;,
          },
          'onHoverEnd': {
            type: &#x22;(e: HoverEvent) => void&#x22;,
            description: &#x22;Handler that is called when a hover interaction ends.&#x22;,
          },
        }"
    />
  </Accordion>

  <Accordion title="Styling">
    <TypeTable
      type="{
          'className': {
            type: &#x22;ClassNameOrFunction<ButtonRenderProps>&#x22;,
            default: &#x22;'react-aria-Button'&#x22;,
            description: &#x22;The CSS className for the element.&#x22;,
          },
          'style': {
            type: &#x22;CSSProperties | ((values: ButtonRenderProps) => CSSProperties)&#x22;,
            description: &#x22;The inline style for the element.&#x22;,
          },
        }"
    />
  </Accordion>

  <Accordion title="Accessibility">
    <TypeTable
      type="{
          'aria-label': {
            type: &#x22;string&#x22;,
            description: &#x22;Defines a string value that labels the element.&#x22;,
          },
          'aria-labelledby': {
            type: &#x22;string&#x22;,
            description: &#x22;Identifies the element(s) that label the current element.&#x22;,
          },
          'aria-describedby': {
            type: &#x22;string&#x22;,
            description: &#x22;Identifies the element(s) that describe the object.&#x22;,
          },
        }"
    />
  </Accordion>
</Accordions>

Default className: `react-aria-Button`

| Render Prop                                                     | CSS Selector           |
| :-------------------------------------------------------------- | :--------------------- |
| `isHovered` <br /> Whether the button is currently hovered.     | `[data-hovered]`       |
| `isPressed` <br /> Whether the button is currently pressed.     | `[data-pressed]`       |
| `isFocused` <br /> Whether the button is focused.               | `[data-focused]`       |
| `isFocusVisible` <br /> Whether the button is keyboard focused. | `[data-focus-visible]` |
| `isDisabled` <br /> Whether the button is disabled.             | `[data-disabled]`      |
| `isPending` <br /> Whether the button is in a pending state.    | `[data-pending]`       |


# ButtonGroup (/docs/components/buttongroup)





# ButtonGroup [#buttongroup]

## Preview [#preview]

<ComponentPreview>
  <ButtonGroup>
    <Button>
      One
    </Button>

    <Button>
      Two
    </Button>

    <Button>
      Three
    </Button>
  </ButtonGroup>
</ComponentPreview>

The `ButtonGroup` component is built with React Aria and styled using StyleX.

## Import [#import]

```tsx
import { ButtonGroup } from '@moul-dev/ui';
```

## Usage [#usage]

Here is a basic example of how to use the `ButtonGroup` component:

```tsx
import { ButtonGroup } from '@moul-dev/ui';

export default function Example() {
  return (
    <ButtonGroup>
      {/* Component content */}
    </ButtonGroup>
  );
}
```


# Card (/docs/components/card)





# Card [#card]

The `Card` component is a flexible container built with React Aria and styled using StyleX. It supports multiple design variants, sizing presets, and section borders.

## Import [#import]

```tsx
import { Card, CardHeader, CardBody, CardFooter } from '@moul-dev/ui';
```

## Preview [#preview]

<ComponentPlayground component="Card" />

***

## Variants [#variants]

Cards support three distinct aesthetic styles to match your design requirements:

### Default (Elevated) [#default-elevated]

Standard surface card featuring clean elevated shadows.

<ComponentPreview>
  <Card className="w-80" variant="default" elevation="1">
    <CardHeader>
      Elevated Card
    </CardHeader>

    <CardBody>
      Standard elevated container with shadow.
    </CardBody>
  </Card>
</ComponentPreview>

```tsx
<Card variant="default" elevation={1}>
  <CardHeader>Elevated Card</CardHeader>
  <CardBody>Standard elevated container with shadow.</CardBody>
</Card>
```

### Flat [#flat]

Clean card with no shadow and a subtle background fill.

<ComponentPreview>
  <Card className="w-80" variant="flat">
    <CardHeader>
      Flat Card
    </CardHeader>

    <CardBody>
      Flat container with subtle solid background.
    </CardBody>
  </Card>
</ComponentPreview>

```tsx
<Card variant="flat">
  <CardHeader>Flat Card</CardHeader>
  <CardBody>Flat container with subtle solid background.</CardBody>
</Card>
```

### Glass [#glass]

Premium translucent glassmorphic look using backdrop blur and opacity.

<ComponentPreview>
  <Card className="w-80" variant="glass">
    <CardHeader>
      Glass Card
    </CardHeader>

    <CardBody>
      Translucent glass card with elegant backdrop filters.
    </CardBody>
  </Card>
</ComponentPreview>

```tsx
<Card variant="glass">
  <CardHeader>Glass Card</CardHeader>
  <CardBody>Translucent glass card with elegant backdrop filters.</CardBody>
</Card>
```

***

## Divided Layout [#divided-layout]

By default, card headers, bodies, and footers flow continuously without separation lines. Passing the `divided` boolean prop adds subtle separator lines between sections.

<ComponentPreview>
  <Card className="w-80">
    <CardHeader>
      Divided Card
    </CardHeader>

    <CardBody>
      Borders separate the header, body, and footer sections.
    </CardBody>

    <CardFooter>
      <Button size="sm">
        Action
      </Button>
    </CardFooter>
  </Card>
</ComponentPreview>

```tsx
<Card divided>
  <CardHeader>Divided Card</CardHeader>
  <CardBody>Borders separate the header, body, and footer sections.</CardBody>
  <CardFooter><Button size="sm">Action</Button></CardFooter>
</Card>
```

***

## Sizes [#sizes]

Choose between different sizing presets to customize block and inline paddings:

### Small (`sm`) [#small-sm]

Compact spacing suitable for dense layouts or list grids.

```tsx
<Card size="sm">...</Card>
```

### Medium (`md`) [#medium-md]

Balanced standard spacing (default).

```tsx
<Card size="md">...</Card>
```

### Large (`lg`) [#large-lg]

Generous breathing spacing ideal for hero sections or details views.

```tsx
<Card size="lg">...</Card>
```

***

## API Reference [#api-reference]

### Card Props [#card-props]

| Prop        | Type                                                 | Default     | Description                                                   |
| :---------- | :--------------------------------------------------- | :---------- | :------------------------------------------------------------ |
| `variant`   | `'default' \| 'flat' \| 'glass'`                     | `'default'` | The visual style variation of the card.                       |
| `size`      | `'sm' \| 'md' \| 'lg'`                               | `'md'`      | Padding sizes applied to the card sections.                   |
| `divided`   | `boolean`                                            | `false`     | When true, renders borders between header, body, and footer.  |
| `elevation` | `0 \| 1 \| 2 \| 3 \| 'none' \| 'sm' \| 'md' \| 'lg'` | `1`         | Shadow elevation level (applies to `'default'` variant only). |


# AreaChart (/docs/components/charts/areachart)





# AreaChart [#areachart]

A modern, responsive area chart built with gradient fills and smooth curves on top of Recharts, styled with StyleX design tokens.

## Preview [#preview]

<div className="grid grid-cols-1 md:grid-cols-2 gap-6 my-6">
  <StatusChartDemo />

  <SpikyAreaChartDemo />
</div>

## Import [#import]

```tsx
import { AreaChart, ChartContainer } from '@moul-dev/ui';
```

## Usage [#usage]

Here is a standard example of rendering an `AreaChart` inside a `ChartContainer`:

```tsx
import { AreaChart, ChartContainer } from '@moul-dev/ui';

export default function Example() {
  const data = [
    { date: 'Jan', Sales: 4000, Revenue: 2400 },
    { date: 'Feb', Sales: 3000, Revenue: 1398 },
    { date: 'Mar', Sales: 2000, Revenue: 9800 },
    { date: 'Apr', Sales: 2780, Revenue: 3908 },
    { date: 'May', Sales: 1890, Revenue: 4800 },
    { date: 'Jun', Sales: 2390, Revenue: 3800 },
  ];

  return (
    <ChartContainer
      title="Monthly Sales Performance"
      description="Comparing sales and revenue over time"
      legend={[{ name: 'Sales' }, { name: 'Revenue' }]}
    >
      <AreaChart
        data={data}
        indexKey="date"
        categories={['Sales', 'Revenue']}
        height={300}
        valueFormatter={(val) => `$${val.toLocaleString()}`}
      />
    </ChartContainer>
  );
}
```

## Edge-to-Edge Sparkline Variant [#edge-to-edge-sparkline-variant]

By setting `edgeToEdge` on `ChartContainer` and hiding axes (`showXAxis={false}`, `showYAxis={false}`), you can create compact sparkline cards:

```tsx
import { AreaChart, ChartContainer } from '@moul-dev/ui';

export default function SparklineExample() {
  const sparkData = [
    { time: '01:00', load: 35 },
    { time: '02:00', load: 42 },
    { time: '03:00', load: 78 },
    { time: '04:00', load: 55 },
    { time: '05:00', load: 60 },
  ];

  return (
    <ChartContainer
      title="Server Load"
      description="Avg 54% over 24h"
      edgeToEdge
    >
      <AreaChart
        data={sparkData}
        indexKey="time"
        categories={['load']}
        height={140}
        showXAxis={false}
        showYAxis={false}
        gridLines={false}
      />
    </ChartContainer>
  );
}
```

## Props [#props]

### AreaChart Props [#areachart-props]

| Prop             | Type                     | Default                                        | Description                                                  |
| :--------------- | :----------------------- | :--------------------------------------------- | :----------------------------------------------------------- |
| `data`           | `any[]`                  | —                                              | Array of data points to plot.                                |
| `indexKey`       | `string`                 | —                                              | Object key to map onto the X-axis.                           |
| `categories`     | `string[]`               | —                                              | Series keys to render as stacked/overlapping gradient areas. |
| `colors`         | `string[]`               | `CHART_COLORS`                                 | Array of color strings or CSS variable references.           |
| `height`         | `number \| string`       | `300`                                          | Height of the chart container in pixels or CSS units.        |
| `gridLines`      | `boolean`                | `true`                                         | Whether to render background horizontal grid lines.          |
| `showXAxis`      | `boolean`                | `true`                                         | Show or hide X-Axis labels.                                  |
| `showYAxis`      | `boolean`                | `true`                                         | Show or hide Y-Axis labels.                                  |
| `valueFormatter` | `(value: any) => string` | —                                              | Formatter function for Y-axis ticks and tooltip values.      |
| `margin`         | `object`                 | `{ top: 10, right: 10, left: -20, bottom: 5 }` | Chart margin offsets.                                        |


# BarChart (/docs/components/charts/barchart)





# BarChart [#barchart]

A highly configurable bar chart supporting vertical layouts, horizontal layouts, stacking, and custom category-based coloring.

## Preview [#preview]

<BarChartDemo />

## Import [#import]

```tsx
import { BarChart, ChartContainer } from '@moul-dev/ui';
```

## Usage [#usage]

### Categorical Bar Chart [#categorical-bar-chart]

Color each bar individually based on its row index (useful for single series):

```tsx
import { BarChart, ChartContainer } from '@moul-dev/ui';

export default function Example() {
  const data = [
    { country: 'United States', Requests: 7530 },
    { country: 'Netherlands', Requests: 4670 },
    { country: 'Singapore', Requests: 1400 },
  ];

  return (
    <ChartContainer title="All requests">
      <BarChart
        data={data}
        indexKey="country"
        categories={['Requests']}
        categorical
        height={300}
      />
    </ChartContainer>
  );
}
```

## Props [#props]

### BarChart Props [#barchart-props]

| Prop             | Type                         | Default        | Description                                 |
| :--------------- | :--------------------------- | :------------- | :------------------------------------------ |
| `data`           | `any[]`                      | —              | Array of data objects.                      |
| `indexKey`       | `string`                     | —              | Key representing the categories.            |
| `categories`     | `string[]`                   | —              | Series dataKeys.                            |
| `colors`         | `string[]`                   | `CHART_COLORS` | Color palette for bars.                     |
| `layout`         | `'horizontal' \| 'vertical'` | `'horizontal'` | Orientation layout.                         |
| `stacked`        | `boolean`                    | `false`        | Enable stacked bars.                        |
| `categorical`    | `boolean`                    | `false`        | Color each bar individually based on index. |
| `valueFormatter` | `(value: any) => string`     | —              | Custom formatter for values.                |
| `height`         | `number \| string`           | `300`          | Height of the chart.                        |
| `gridLines`      | `boolean`                    | `true`         | Show horizontal/vertical grid lines.        |


# DoughnutChart (/docs/components/charts/doughnutchart)





# DoughnutChart [#doughnutchart]

A beautiful doughnut (pie) chart featuring rounded sectors, animations, and active segment highlight interactions.

## Preview [#preview]

<DoughnutChartDemo />

## Import [#import]

```tsx
import { DoughnutChart, ChartContainer } from '@moul-dev/ui';
```

## Usage [#usage]

```tsx
import { DoughnutChart, ChartContainer } from '@moul-dev/ui';

export default function Example() {
  const data = [
    { country: 'United States', value: 7530 },
    { country: 'Netherlands', value: 4670 },
    { country: 'Singapore', value: 1400 },
  ];

  return (
    <ChartContainer title="Request distribution">
      <DoughnutChart
        data={data}
        nameKey="country"
        valueKey="value"
        height={260}
      />
    </ChartContainer>
  );
}
```

## Props [#props]

### DoughnutChart Props [#doughnutchart-props]

| Prop             | Type                     | Default        | Description                        |
| :--------------- | :----------------------- | :------------- | :--------------------------------- |
| `data`           | `any[]`                  | —              | Array of category data.            |
| `nameKey`        | `string`                 | —              | Key representing slice labels.     |
| `valueKey`       | `string`                 | —              | Key representing slice quantities. |
| `colors`         | `string[]`               | `CHART_COLORS` | Array of colors for slices.        |
| `innerRadius`    | `number \| string`       | `'65%'`        | Inner circle diameter cut-out.     |
| `outerRadius`    | `number \| string`       | `'85%'`        | Outer circle diameter.             |
| `paddingAngle`   | `number`                 | `3`            | Angle gaps between slices.         |
| `valueFormatter` | `(value: any) => string` | —              | Tooltip values formatter.          |
| `height`         | `number \| string`       | `300`          | Render height.                     |


# LineChart (/docs/components/charts/linechart)





# LineChart [#linechart]

A premium, interactive line chart designed for time-series and trend data, built on top of Recharts and styled with StyleX design tokens.

## Preview [#preview]

<LineChartDemo />

## Edge-to-Edge Area Charts [#edge-to-edge-area-charts]

Create compact sparklines or real-time metric cards by combining `AreaChart` with an `edgeToEdge` styled `ChartContainer`. Hiding the axes and grid lines allows the chart to align perfectly with the container's borders.

<div className="grid grid-cols-1 md:grid-cols-2 gap-6 my-6">
  <StatusChartDemo />

  <SpikyAreaChartDemo />
</div>

## Import [#import]

```tsx
import { LineChart, AreaChart, ChartContainer } from '@moul-dev/ui';
```

## Usage [#usage]

Here is a basic example of how to render a timeseries chart inside a `ChartContainer`:

```tsx
import { LineChart, ChartContainer } from '@moul-dev/ui';

export default function Example() {
  const data = [
    { date: '08:00', Requests: 120, Users: 80 },
    { date: '12:00', Requests: 450, Users: 320 },
    { date: '16:00', Requests: 890, Users: 520 },
  ];

  return (
    <ChartContainer title="Request Trends" legend={[{ name: 'Requests' }, { name: 'Users' }]}>
      <LineChart
        data={data}
        indexKey="date"
        categories={['Requests', 'Users']}
        height={300}
      />
    </ChartContainer>
  );
}
```

## Props [#props]

### LineChart Props [#linechart-props]

| Prop             | Type                     | Default        | Description                                       |
| :--------------- | :----------------------- | :------------- | :------------------------------------------------ |
| `data`           | `any[]`                  | —              | Array of data objects to plot.                    |
| `indexKey`       | `string`                 | —              | The object key to plot on the X-axis.             |
| `categories`     | `string[]`               | —              | Keys corresponding to series lines.               |
| `colors`         | `string[]`               | `CHART_COLORS` | Array of hex/style variables to color the lines.  |
| `height`         | `number \| string`       | `300`          | Height of the chart container.                    |
| `gridLines`      | `boolean`                | `true`         | Whether to display background grid lines.         |
| `showXAxis`      | `boolean`                | `true`         | Show/hide X-Axis ticks.                           |
| `showYAxis`      | `boolean`                | `true`         | Show/hide Y-Axis ticks.                           |
| `valueFormatter` | `(value: any) => string` | —              | Function to format the Y-Axis and Tooltip values. |


# Percentage (/docs/components/charts/percentage)





# Percentage [#percentage]

Progress indicators that render percentage values in horizontal bars or SVG circular progress rings.

## Preview [#preview]

<PercentageDemo />

## Import [#import]

```tsx
import { PercentageBar, PercentageCircle } from '@moul-dev/ui';
```

## Usage [#usage]

### Horizontal Percentage Bar [#horizontal-percentage-bar]

```tsx
import { PercentageBar } from '@moul-dev/ui';

export default function Example() {
  return (
    <PercentageBar
      value={85}
      label="Task Completion"
      size="md"
    />
  );
}
```

### Circular Progress Ring [#circular-progress-ring]

```tsx
import { PercentageCircle } from '@moul-dev/ui';

export default function Example() {
  return (
    <PercentageCircle
      value={75}
      label="Server CPU"
      size={80}
    />
  );
}
```

## Props [#props]

### PercentageBar Props [#percentagebar-props]

| Prop            | Type                   | Default              | Description                        |
| :-------------- | :--------------------- | :------------------- | :--------------------------------- |
| `value`         | `number`               | —                    | Progress percentage (0 - 100).     |
| `label`         | `ReactNode`            | —                    | Text label shown above the bar.    |
| `showValueText` | `boolean`              | `true`               | Show percentage text on the right. |
| `color`         | `string`               | `tokens.colorChart1` | Color of the progress filled bar.  |
| `size`          | `'sm' \| 'md' \| 'lg'` | `'md'`               | Height thickness.                  |

### PercentageCircle Props [#percentagecircle-props]

| Prop            | Type        | Default              | Description                                  |
| :-------------- | :---------- | :------------------- | :------------------------------------------- |
| `value`         | `number`    | —                    | Progress percentage (0 - 100).               |
| `label`         | `ReactNode` | —                    | Label shown underneath the circle.           |
| `showValueText` | `boolean`   | `true`               | Display progress percentage inside the ring. |
| `color`         | `string`    | `tokens.colorChart1` | Color of the filled ring segment.            |
| `size`          | `number`    | `80`                 | Diameter size in pixels.                     |
| `strokeWidth`   | `number`    | `8`                  | Border stroke thickness of the circle.       |


# Stat (/docs/components/charts/stat)





# Stat [#stat]

A KPI metric card component displaying a large value, label, and trend indicators with status coloring.

## Preview [#preview]

<StatDemo />

## Import [#import]

```tsx
import { Stat } from '@moul-dev/ui';
```

## Usage [#usage]

```tsx
import { Stat } from '@moul-dev/ui';

export default function Example() {
  return (
    <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
      <Stat
        label="Total Requests"
        value="15,820"
        trend="+12.3%"
        trendDirection="up"
        trendLabel="vs last month"
      />
      <Stat
        label="Errors"
        value="84"
        trend="-8.4%"
        trendDirection="down"
        trendLabel="vs yesterday"
      />
    </div>
  );
}
```

## Props [#props]

### Stat Props [#stat-props]

| Prop             | Type                          | Default     | Description                             |
| :--------------- | :---------------------------- | :---------- | :-------------------------------------- |
| `label`          | `ReactNode`                   | —           | Label or title for the stat card.       |
| `value`          | `ReactNode`                   | —           | Main value text.                        |
| `trend`          | `string \| number`            | —           | Trend percentage or text.               |
| `trendDirection` | `'up' \| 'down' \| 'neutral'` | `'neutral'` | Arrow direction and badge styling.      |
| `trendLabel`     | `ReactNode`                   | —           | Additional description text for footer. |


# TopList (/docs/components/charts/toplist)





# TopList [#toplist]

A ranked list visualization that maps rows with custom mini horizontal progress bars representing the values relative to the maximum list value.

## Preview [#preview]

<TopListDemo />

## Import [#import]

```tsx
import { TopList } from '@moul-dev/ui';
```

## Usage [#usage]

```tsx
import { TopList, ChartContainer } from '@moul-dev/ui';

export default function Example() {
  const data = [
    { label: 'United States', value: 7530 },
    { label: 'Netherlands', value: 4670 },
    { label: 'Singapore', value: 1400 },
  ];

  return (
    <ChartContainer title="Top list">
      <TopList data={data} />
    </ChartContainer>
  );
}
```

## Props [#props]

### TopList Props [#toplist-props]

| Prop             | Type                        | Default              | Description                                                         |
| :--------------- | :-------------------------- | :------------------- | :------------------------------------------------------------------ |
| `data`           | `TopListItem[]`             | —                    | Array of `{ label: string, value: number, color?: string }`.        |
| `maxValue`       | `number`                    | —                    | Override maximum scale value. Defaults to maximum value in dataset. |
| `barColor`       | `string`                    | `tokens.colorChart1` | Default color for all progress bars.                                |
| `multiColor`     | `boolean`                   | `false`              | Enable index-based color mapping for progress bars.                 |
| `valueFormatter` | `(value: number) => string` | —                    | Custom formatter for values.                                        |


# Checkbox (/docs/components/checkbox)





# Checkbox [#checkbox]

## Preview [#preview]

<ComponentPreview>
  <div className="flex flex-col gap-2">
    <Checkbox>
      Unchecked
    </Checkbox>

    <Checkbox>
      Checked
    </Checkbox>

    <Checkbox>
      Disabled
    </Checkbox>
  </div>
</ComponentPreview>

The `Checkbox` component is built with React Aria and styled using StyleX.

## Import [#import]

```tsx
import { Checkbox } from '@moul-dev/ui';
```

## Usage [#usage]

Here is a basic example of how to use the `Checkbox` component:

```tsx
import { Checkbox } from '@moul-dev/ui';

export default function Example() {
  return (
    <Checkbox>
      Checkbox Label
    </Checkbox>
  );
}
```

## Variants [#variants]

The `Checkbox` component supports three visual variants: `primary` (default), `secondary`, and `tertiary`.

<ComponentPreview>
  <div className="flex flex-col gap-4">
    <div className="flex flex-col gap-2">
      <span className="text-sm font-medium text-neutral-500">
        Primary (default)
      </span>

      <div className="flex gap-4">
        <Checkbox variant="primary">
          Unchecked
        </Checkbox>

        <Checkbox variant="primary">
          Checked
        </Checkbox>
      </div>
    </div>

    <div className="flex flex-col gap-2">
      <span className="text-sm font-medium text-neutral-500">
        Secondary
      </span>

      <div className="flex gap-4">
        <Checkbox variant="secondary">
          Unchecked
        </Checkbox>

        <Checkbox variant="secondary">
          Checked
        </Checkbox>
      </div>
    </div>

    <div className="flex flex-col gap-2">
      <span className="text-sm font-medium text-neutral-500">
        Tertiary
      </span>

      <div className="flex gap-4">
        <Checkbox variant="tertiary">
          Unchecked
        </Checkbox>

        <Checkbox variant="tertiary">
          Checked
        </Checkbox>
      </div>
    </div>
  </div>
</ComponentPreview>

### Primary Variant [#primary-variant]

The primary variant uses the primary accent brand colors, suited for main user actions.

```tsx
<Checkbox variant="primary" defaultSelected>Primary</Checkbox>
```

### Secondary Variant [#secondary-variant]

The secondary variant uses monochrome neutral styling, providing a clean alternative for lists and tables.

```tsx
<Checkbox variant="secondary" defaultSelected>Secondary</Checkbox>
```

### Tertiary Variant [#tertiary-variant]

The tertiary variant is a hollow outline checkbox style that stays transparent and applies primary colors to the border and checkmark itself.

```tsx
<Checkbox variant="tertiary" defaultSelected>Tertiary</Checkbox>
```

## Props [#props]

### Checkbox Props [#checkbox-props]

<TypeTable
  type="{
  'variant': {
    type: &#x22;'primary' | 'secondary' | 'tertiary'&#x22;,
    default: &#x22;'primary'&#x22;,
    description: &#x22;The visual style variant of the checkbox.&#x22;,
  },
  'isSelected': {
    type: &#x22;boolean&#x22;,
    description: &#x22;Whether the checkbox is checked (controlled).&#x22;,
  },
  'defaultSelected': {
    type: &#x22;boolean&#x22;,
    description: &#x22;Whether the checkbox is checked by default (uncontrolled).&#x22;,
  },
  'isIndeterminate': {
    type: &#x22;boolean&#x22;,
    description: &#x22;Whether the checkbox is indeterminate.&#x22;,
  },
  'isDisabled': {
    type: &#x22;boolean&#x22;,
    default: &#x22;false&#x22;,
    description: &#x22;Whether the checkbox is disabled.&#x22;,
  },
}"
/>

<Accordions>
  <Accordion title="Value">
    <TypeTable
      type="{
          'onChange': {
            type: &#x22;(isSelected: boolean) => void&#x22;,
            description: &#x22;Handler called when the checked state changes.&#x22;,
          },
        }"
    />
  </Accordion>

  <Accordion title="Styling">
    <TypeTable
      type="{
          'className': {
            type: &#x22;ClassNameOrFunction<CheckboxRenderProps>&#x22;,
            default: &#x22;'react-aria-Checkbox'&#x22;,
            description: &#x22;The CSS className for the element.&#x22;,
          },
        }"
    />
  </Accordion>
</Accordions>

Default className: `react-aria-Checkbox`

| Render Prop                                                       | CSS Selector           |
| :---------------------------------------------------------------- | :--------------------- |
| `isSelected` <br /> Whether the checkbox is selected.             | `[data-selected]`      |
| `isIndeterminate` <br /> Whether the checkbox is indeterminate.   | `[data-indeterminate]` |
| `isHovered` <br /> Whether the checkbox is hovered.               | `[data-hovered]`       |
| `isPressed` <br /> Whether the checkbox is pressed.               | `[data-pressed]`       |
| `isFocused` <br /> Whether the checkbox is focused.               | `[data-focused]`       |
| `isFocusVisible` <br /> Whether the checkbox is keyboard focused. | `[data-focus-visible]` |
| `isDisabled` <br /> Whether the checkbox is disabled.             | `[data-disabled]`      |


# CheckboxGroup (/docs/components/checkboxgroup)





# CheckboxGroup [#checkboxgroup]

## Preview [#preview]

<ComponentPreview>
  <CheckboxGroup label="Notifications" description="Choose how you want to be notified.">
    <Checkbox value="email">
      Email
    </Checkbox>

    <Checkbox value="sms">
      SMS
    </Checkbox>
  </CheckboxGroup>
</ComponentPreview>

The `CheckboxGroup` component is built with React Aria and styled using StyleX.

## Import [#import]

```tsx
import { CheckboxGroup, Checkbox } from '@moul-dev/ui';
```

## Usage [#usage]

Here is a basic example of how to use the `CheckboxGroup` component:

```tsx
import { CheckboxGroup, Checkbox } from '@moul-dev/ui';

export default function Example() {
  return (
    <CheckboxGroup label="Settings" description="Configure your preferences">
      <Checkbox value="cookies">Accept cookies</Checkbox>
      <Checkbox value="marketing">Receive marketing</Checkbox>
    </CheckboxGroup>
  );
}
```

## Features [#features]

### Group Variants [#group-variants]

Setting `variant` on `CheckboxGroup` propagates the variant style (`primary`, `secondary`, or `tertiary`) to all nested `Checkbox` components automatically.

<ComponentPreview>
  <div className="flex flex-col gap-6">
    <CheckboxGroup label="Primary Group" variant="primary">
      <Checkbox value="1">
        Checkbox A
      </Checkbox>

      <Checkbox value="2">
        Checkbox B
      </Checkbox>
    </CheckboxGroup>

    <CheckboxGroup label="Secondary Group" variant="secondary">
      <Checkbox value="1">
        Checkbox A
      </Checkbox>

      <Checkbox value="2">
        Checkbox B
      </Checkbox>
    </CheckboxGroup>

    <CheckboxGroup label="Tertiary Group" variant="tertiary">
      <Checkbox value="1">
        Checkbox A
      </Checkbox>

      <Checkbox value="2">
        Checkbox B
      </Checkbox>
    </CheckboxGroup>
  </div>
</ComponentPreview>

```tsx
// Nested checkboxes inherit the group's secondary variant
<CheckboxGroup label="Roles" variant="secondary">
  <Checkbox value="admin">Admin</Checkbox>
  <Checkbox value="user">User</Checkbox>
</CheckboxGroup>
```

### Orientation [#orientation]

Lays out checkboxes vertically (default) or horizontally using the `orientation` prop.

<ComponentPreview>
  <CheckboxGroup label="Horizontal Layout" orientation="horizontal" variant="primary">
    <Checkbox value="vertical">
      Vertical option
    </Checkbox>

    <Checkbox value="horizontal">
      Horizontal option
    </Checkbox>

    <Checkbox value="grid">
      Grid option
    </Checkbox>
  </CheckboxGroup>
</ComponentPreview>

```tsx
<CheckboxGroup label="Horizontal Layout" orientation="horizontal">
  <Checkbox value="1">Option 1</Checkbox>
  <Checkbox value="2">Option 2</Checkbox>
</CheckboxGroup>
```

## Props [#props]

### CheckboxGroup Props [#checkboxgroup-props]

<TypeTable
  type="{
  'variant': {
    type: &#x22;'primary' | 'secondary' | 'tertiary'&#x22;,
    default: &#x22;'primary'&#x22;,
    description: &#x22;The visual style variant applied to checkboxes inside the group.&#x22;,
  },
  'orientation': {
    type: &#x22;'horizontal' | 'vertical'&#x22;,
    default: &#x22;'vertical'&#x22;,
    description: &#x22;The orientation of the checkboxes within the group.&#x22;,
  },
  'value': {
    type: &#x22;string[]&#x22;,
    description: &#x22;The values of the selected checkboxes (controlled).&#x22;,
  },
  'defaultValue': {
    type: &#x22;string[]&#x22;,
    description: &#x22;The values of the initially selected checkboxes (uncontrolled).&#x22;,
  },
  'isDisabled': {
    type: &#x22;boolean&#x22;,
    default: &#x22;false&#x22;,
    description: &#x22;Whether all checkboxes within the group are disabled.&#x22;,
  },
  'isInvalid': {
    type: &#x22;boolean&#x22;,
    description: &#x22;Whether the input value is invalid.&#x22;,
  },
}"
/>

<Accordions>
  <Accordion title="Value">
    <TypeTable
      type="{
          'onChange': {
            type: &#x22;(value: string[]) => void&#x22;,
            description: &#x22;Handler called when the selection changes.&#x22;,
          },
        }"
    />
  </Accordion>

  <Accordion title="Styling">
    <TypeTable
      type="{
          'className': {
            type: &#x22;ClassNameOrFunction<CheckboxGroupRenderProps>&#x22;,
            default: &#x22;'react-aria-CheckboxGroup'&#x22;,
            description: &#x22;The CSS className for the group.&#x22;,
          },
        }"
    />
  </Accordion>
</Accordions>

Default className: `react-aria-CheckboxGroup`

| Render Prop                                            | CSS Selector      |
| :----------------------------------------------------- | :---------------- |
| `isDisabled` <br /> Whether the group is disabled.     | `[data-disabled]` |
| `isInvalid` <br /> Whether the group value is invalid. | `[data-invalid]`  |


# ComboBox (/docs/components/combobox)





# ComboBox [#combobox]

## Preview [#preview]

<ComponentPreview>
  <ComboBox label="Favorite Animal" placeholder="Search...">
    <ComboBoxItem id="cat">
      Cat
    </ComboBoxItem>

    <ComboBoxItem id="dog">
      Dog
    </ComboBoxItem>

    <ComboBoxItem id="panda">
      Panda
    </ComboBoxItem>
  </ComboBox>
</ComponentPreview>

The `ComboBox` component is built with React Aria and styled using StyleX.

## Import [#import]

```tsx
import { ComboBox } from '@moul-dev/ui';
```

## Usage [#usage]

Here is a basic example of how to use the `ComboBox` component:

```tsx
import { ComboBox } from '@moul-dev/ui';

export default function Example() {
  return (
    <ComboBox>
      {/* Component content */}
    </ComboBox>
  );
}
```

## Multi-select with TagGroup [#multi-select-with-taggroup]

You can build a multi-select ComboBox by managing the selection state in a list/set, filtering out the selected items from the dropdown, and rendering them as a `TagGroup` below the ComboBox.

<ComponentPreview>
  <ComboBoxTagGroupDemo />
</ComponentPreview>

```tsx
import { ComboBox, ComboBoxItem, TagGroup, Tag } from '@moul-dev/ui';
import { useState } from 'react';

export default function Example() {
  const provinces = [
    { id: 'phnom-penh', name: 'Phnom Penh' },
    { id: 'siem-reap', name: 'Siem Reap' },
    { id: 'battambang', name: 'Battambang' },
    { id: 'sihanoukville', name: 'Sihanoukville' },
    { id: 'kampot', name: 'Kampot' },
    { id: 'kandal', name: 'Kandal' },
    { id: 'kampong-cham', name: 'Kampong Cham' },
    { id: 'koh-kong', name: 'Koh Kong' },
    { id: 'kep', name: 'Kep' },
  ];

  const [selectedKeys, setSelectedKeys] = useState<Set<any>>(new Set());
  const [inputValue, setInputValue] = useState('');

  const availableProvinces = provinces.filter(
    (p) => !selectedKeys.has(p.id)
  );

  const handleSelectionChange = (key: any) => {
    if (key) {
      setSelectedKeys((prev) => {
        const next = new Set(prev);
        next.add(key);
        return next;
      });
      setInputValue('');
    }
  };

  const handleRemove = (keys: Set<any>) => {
    setSelectedKeys((prev) => {
      const next = new Set(prev);
      for (const k of keys) {
        next.delete(k);
      }
      return next;
    });
  };

  return (
    <div className="w-full max-w-sm flex flex-col gap-4">
      <ComboBox
        label="Cambodian Provinces"
        placeholder="Select a province"
        inputValue={inputValue}
        onInputChange={setInputValue}
        onSelectionChange={handleSelectionChange}
        selectedKey={null}
      >
        {availableProvinces.map((province) => (
          <ComboBoxItem key={province.id} id={province.id}>
            {province.name}
          </ComboBoxItem>
        ))}
      </ComboBox>

      {selectedKeys.size > 0 && (
        <TagGroup
          label="Selected Provinces"
          onRemove={handleRemove}
          variant="primary"
        >
          {[...selectedKeys].map((key) => {
            const province = provinces.find((p) => p.id === key);
            return (
              <Tag key={key} id={key}>
                {province?.name || key}
              </Tag>
            );
          })}
        </TagGroup>
      )}
    </div>
  );
}
```

## Props [#props]

### ComboBox Props [#combobox-props]

<TypeTable
  type="{
  'selectedKey': {
    type: &#x22;Key&#x22;,
    description: &#x22;The selected key (controlled).&#x22;,
  },
  'defaultSelectedKey': {
    type: &#x22;Key&#x22;,
    description: &#x22;The default selected key (uncontrolled).&#x22;,
  },
  'inputValue': {
    type: &#x22;string&#x22;,
    description: &#x22;The input field value (controlled).&#x22;,
  },
  'defaultInputValue': {
    type: &#x22;string&#x22;,
    description: &#x22;The default input field value (uncontrolled).&#x22;,
  },
  'isDisabled': {
    type: &#x22;boolean&#x22;,
    default: &#x22;false&#x22;,
    description: &#x22;Whether the combobox is disabled.&#x22;,
  },
}"
/>

<Accordions>
  <Accordion title="Value">
    <TypeTable
      type="{
          'onSelectionChange': {
            type: &#x22;(key: Key) => void&#x22;,
            description: &#x22;Handler called when selection changes.&#x22;,
          },
          'onInputChange': {
            type: &#x22;(value: string) => void&#x22;,
            description: &#x22;Handler called when input value changes.&#x22;,
          },
        }"
    />
  </Accordion>

  <Accordion title="Styling">
    <TypeTable
      type="{
          'className': {
            type: &#x22;ClassNameOrFunction<ComboBoxRenderProps>&#x22;,
            default: &#x22;'react-aria-ComboBox'&#x22;,
            description: &#x22;The CSS className.&#x22;,
          },
        }"
    />
  </Accordion>
</Accordions>

Default className: `react-aria-ComboBox`

| Render Prop                                                       | CSS Selector           |
| :---------------------------------------------------------------- | :--------------------- |
| `isOpen` <br /> Whether the combobox list popover is open.        | `[data-open]`          |
| `isFocused` <br /> Whether the combobox is focused.               | `[data-focused]`       |
| `isFocusVisible` <br /> Whether the combobox is keyboard focused. | `[data-focus-visible]` |
| `isDisabled` <br /> Whether the combobox is disabled.             | `[data-disabled]`      |


# Form (/docs/components/form)





# Form [#form]

## Preview [#preview]

<ComponentPreview>
  <FormDemo />
</ComponentPreview>

The `Form` component is built with React Aria and styled using StyleX.

## Import [#import]

```tsx
import { Form } from '@moul-dev/ui';
```

## Usage [#usage]

Here is a basic example of how to use the `Form` component:

```tsx
import { Form } from '@moul-dev/ui';

export default function Example() {
  return (
    <Form>
      {/* Component content */}
    </Form>
  );
}
```

## Props [#props]

### Form Props [#form-props]

<TypeTable
  type="{
  'validationBehavior': {
    type: &#x22;'native' | 'aria'&#x22;,
    default: &#x22;'native'&#x22;,
    description: &#x22;Validation behavior settings.&#x22;,
  },
}"
/>

<Accordions>
  <Accordion title="Events">
    <TypeTable
      type="{
          'onSubmit': {
            type: &#x22;(e: FormEvent) => void&#x22;,
            description: &#x22;Fires when submitting the form successfully.&#x22;,
          },
          'onReset': {
            type: &#x22;(e: FormEvent) => void&#x22;,
            description: &#x22;Fires when resetting form values.&#x22;,
          },
        }"
    />
  </Accordion>

  <Accordion title="Styling">
    <TypeTable
      type="{
          'className': {
            type: &#x22;string&#x22;,
            description: &#x22;The CSS className.&#x22;,
          },
        }"
    />
  </Accordion>
</Accordions>

Default className: `react-aria-Form`


# InputOTP (/docs/components/inputotp)





<div style="{ display: 'none' }">
  OTP, InputOTP, One-Time Passcode, Verification Code, Caret, Separator, input-otp
</div>

# InputOTP [#inputotp]

## Preview [#preview]

<ComponentPlayground component="InputOTP" />

The `InputOTP` component is a flexible, highly accessible one-time password input component. It is built on top of the headless `input-otp` library by `@guilhermerodz` and styled using StyleX.

## Import [#import]

```tsx
import {
  InputOTP,
  InputOTPGroup,
  InputOTPSlot,
  InputOTPSeparator
} from '@moul-dev/ui';
```

## Features [#features]

### Basic Layout (6-digit) [#basic-layout-6-digit]

A standard 6-digit passcode layout utilizing a separator in the middle.

<ComponentPreview>
  <InputOTPDemo />
</ComponentPreview>

```tsx
import { useState } from 'react';
import {
  InputOTP,
  InputOTPGroup,
  InputOTPSlot,
  InputOTPSeparator
} from '@moul-dev/ui';

export default function Example() {
  const [value, setValue] = useState('');

  return (
    <InputOTP maxLength={6} value={value} onChange={setValue}>
      <InputOTPGroup>
        <InputOTPSlot index={0} />
        <InputOTPSlot index={1} />
        <InputOTPSlot index={2} />
      </InputOTPGroup>
      <InputOTPSeparator />
      <InputOTPGroup>
        <InputOTPSlot index={3} />
        <InputOTPSlot index={4} />
        <InputOTPSlot index={5} />
      </InputOTPGroup>
    </InputOTP>
  );
}
```

### Label & Helper Text [#label--helper-text]

The component supports standard form control label and description props.

```tsx
<InputOTP
  maxLength={4}
  label="Security Code"
  description="Enter the 4-digit code sent to your email."
>
  <InputOTPGroup>
    <InputOTPSlot index={0} />
    <InputOTPSlot index={1} />
    <InputOTPSlot index={2} />
    <InputOTPSlot index={3} />
  </InputOTPGroup>
</InputOTP>
```

### Validation State [#validation-state]

Marking the input as invalid highlights the slot borders and renders a custom error message.

```tsx
<InputOTP
  maxLength={4}
  label="Verification Code"
  isInvalid={true}
  errorMessage="The verification code you entered is incorrect."
>
  <InputOTPGroup>
    <InputOTPSlot index={0} />
    <InputOTPSlot index={1} />
    <InputOTPSlot index={2} />
    <InputOTPSlot index={3} />
  </InputOTPGroup>
</InputOTP>
```

### Custom Separator [#custom-separator]

You can provide any React node inside `InputOTPSeparator` to customize the visual divider.

```tsx
<InputOTP maxLength={4}>
  <InputOTPGroup>
    <InputOTPSlot index={0} />
    <InputOTPSlot index={1} />
  </InputOTPGroup>
  <InputOTPSeparator>-</InputOTPSeparator>
  <InputOTPGroup>
    <InputOTPSlot index={2} />
    <InputOTPSlot index={3} />
  </InputOTPGroup>
</InputOTP>
```


# Kbd (/docs/components/kbd)





# Kbd [#kbd]

## Preview [#preview]

<ComponentPreview>
  <div className="flex gap-2">
    <Kbd>
      ⌘
    </Kbd>

    <Kbd>
      K
    </Kbd>
  </div>
</ComponentPreview>

The `Kbd` component is built with React Aria and styled using StyleX.

## Import [#import]

```tsx
import { Kbd } from '@moul-dev/ui';
```

## Usage [#usage]

Here is a basic example of how to use the `Kbd` component:

```tsx
import { Kbd } from '@moul-dev/ui';

export default function Example() {
  return (
    <Kbd>
      {/* Component content */}
    </Kbd>
  );
}
```


# Link (/docs/components/link)





# Link [#link]

## Preview [#preview]

<ComponentPreview>
  <Link href="#">
    Visit Khmer Dev
  </Link>
</ComponentPreview>

The `Link` component is built with React Aria and styled using StyleX.

## Import [#import]

```tsx
import { Link } from '@moul-dev/ui';
```

## Usage [#usage]

Here is a basic example of how to use the `Link` component:

```tsx
import { Link } from '@moul-dev/ui';

export default function Example() {
  return (
    <Link>
      {/* Component content */}
    </Link>
  );
}
```

## Props [#props]

### Link Props [#link-props]

<TypeTable
  type="{
  'variant': {
    type: &#x22;'primary' | 'secondary' | 'tertiary' | 'outline' | 'ghost' | 'danger' | 'danger-soft'&#x22;,
    default: &#x22;'primary'&#x22;,
    description: &#x22;The visual style variant of the link.&#x22;,
  },
  'isDisabled': {
    type: &#x22;boolean&#x22;,
    default: &#x22;false&#x22;,
    description: &#x22;Whether the link is disabled.&#x22;,
  },
  'href': {
    type: &#x22;string&#x22;,
    description: &#x22;The URL that the hyperlink points to.&#x22;,
  },
  'target': {
    type: &#x22;string&#x22;,
    description: &#x22;Where to display the linked URL.&#x22;,
  },
}"
/>

<Accordions>
  <Accordion title="Events">
    <TypeTable
      type="{
          'onPress': {
            type: &#x22;(e: PressEvent) => void&#x22;,
            description: &#x22;Handler called when the link is pressed.&#x22;,
          },
        }"
    />
  </Accordion>

  <Accordion title="Styling">
    <TypeTable
      type="{
          'className': {
            type: &#x22;ClassNameOrFunction<LinkRenderProps>&#x22;,
            default: &#x22;'react-aria-Link'&#x22;,
            description: &#x22;The CSS className for the element.&#x22;,
          },
        }"
    />
  </Accordion>
</Accordions>

Default className: `react-aria-Link`

| Render Prop                                                   | CSS Selector           |
| :------------------------------------------------------------ | :--------------------- |
| `isCurrent` <br /> Whether the link is the current item.      | `[data-current]`       |
| `isHovered` <br /> Whether the link is hovered.               | `[data-hovered]`       |
| `isPressed` <br /> Whether the link is pressed.               | `[data-pressed]`       |
| `isFocused` <br /> Whether the link is focused.               | `[data-focused]`       |
| `isFocusVisible` <br /> Whether the link is keyboard focused. | `[data-focus-visible]` |
| `isDisabled` <br /> Whether the link is disabled.             | `[data-disabled]`      |


# Modal (/docs/components/modal)





# Modal [#modal]

## Preview [#preview]

<ComponentPreview>
  <ModalDemo />
</ComponentPreview>

The `Modal` component is built with React Aria and styled using StyleX.

## Import [#import]

```tsx
import { Modal } from '@moul-dev/ui';
```

## Usage [#usage]

Here is a basic example of how to use the `Modal` component:

```tsx
import { Modal } from '@moul-dev/ui';

export default function Example() {
  return (
    <Modal>
      {/* Component content */}
    </Modal>
  );
}
```

## Sizing and Variants [#sizing-and-variants]

The `Modal` component supports size variants via the `size` prop:

* `sm`: Max width of `400px` on desktop.
* `md`: Max width of `500px` on desktop (default).
* `lg`: Max width of `640px` on desktop.

```tsx
<Modal size="sm">
  {/* Small Modal */}
</Modal>
```

## Mobile Responsive Layout [#mobile-responsive-layout]

On mobile viewports (`<= 640px`), the modal is optimized to behave like a bottom drawer/sheet:

* Aligned to the bottom of the screen.
* Extends to `100%` viewport width.
* Bottom corner radiuses are set to `0` for seamless edge-to-edge styling.
* Renders with a smooth, subtle fade-in and slide-up animation from the bottom of the viewport.

## Props [#props]

### Modal Props [#modal-props]

<TypeTable
  type="{
  'isOpen': {
    type: &#x22;boolean&#x22;,
    description: &#x22;Whether the modal overlay wrapper is open (controlled).&#x22;,
  },
  'defaultOpen': {
    type: &#x22;boolean&#x22;,
    description: &#x22;Whether the modal is initially open (uncontrolled).&#x22;,
  },
  'isDismissable': {
    type: &#x22;boolean&#x22;,
    default: &#x22;false&#x22;,
    description: &#x22;Whether clicking outside or pressing Escape closes the modal overlay.&#x22;,
  },
}"
/>

<Accordions>
  <Accordion title="Value">
    <TypeTable
      type="{
          'onOpenChange': {
            type: &#x22;(isOpen: boolean) => void&#x22;,
            description: &#x22;Handler called when open state changes.&#x22;,
          },
        }"
    />
  </Accordion>

  <Accordion title="Styling">
    <TypeTable
      type="{
          'className': {
            type: &#x22;ClassNameOrFunction<ModalRenderProps>&#x22;,
            default: &#x22;'react-aria-Modal'&#x22;,
            description: &#x22;The CSS className.&#x22;,
          },
        }"
    />
  </Accordion>
</Accordions>

Default className: `react-aria-Modal`

| Render Prop                                                       | CSS Selector      |
| :---------------------------------------------------------------- | :---------------- |
| `isOpen` <br /> Whether the modal is open.                        | `[data-open]`     |
| `isEntering` <br /> Whether the entrance transition is animating. | `[data-entering]` |
| `isExiting` <br /> Whether the exit transition is animating.      | `[data-exiting]`  |


# NumberField (/docs/components/numberfield)





# NumberField [#numberfield]

## Preview [#preview]

<ComponentPreview>
  <NumberField label="Quantity" defaultValue="5" />
</ComponentPreview>

The `NumberField` component is built with React Aria and styled using StyleX.

## Import [#import]

```tsx
import { NumberField } from '@moul-dev/ui';
```

## Usage [#usage]

Here is a basic example of how to use the `NumberField` component:

```tsx
import { NumberField } from '@moul-dev/ui';

export default function Example() {
  return (
    <NumberField>
      {/* Component content */}
    </NumberField>
  );
}
```

## Props [#props]

### NumberField Props [#numberfield-props]

<TypeTable
  type="{
  'variant': {
    type: &#x22;'primary' | 'secondary'&#x22;,
    default: &#x22;'primary'&#x22;,
    description: &#x22;The visual style variant of the number field.&#x22;,
  },
  'value': {
    type: &#x22;number&#x22;,
    description: &#x22;The current value (controlled).&#x22;,
  },
  'defaultValue': {
    type: &#x22;number&#x22;,
    description: &#x22;The default value (uncontrolled).&#x22;,
  },
  'minValue': {
    type: &#x22;number&#x22;,
    description: &#x22;The minimum allowed value.&#x22;,
  },
  'maxValue': {
    type: &#x22;number&#x22;,
    description: &#x22;The maximum allowed value.&#x22;,
  },
  'step': {
    type: &#x22;number&#x22;,
    default: &#x22;1&#x22;,
    description: &#x22;The amount to increment or decrement the value on interaction.&#x22;,
  },
  'isDisabled': {
    type: &#x22;boolean&#x22;,
    default: &#x22;false&#x22;,
    description: &#x22;Whether the field is disabled.&#x22;,
  },
}"
/>

<Accordions>
  <Accordion title="Value">
    <TypeTable
      type="{
          'onChange': {
            type: &#x22;(value: number) => void&#x22;,
            description: &#x22;Handler called when the value changes.&#x22;,
          },
        }"
    />
  </Accordion>

  <Accordion title="Styling">
    <TypeTable
      type="{
          'className': {
            type: &#x22;ClassNameOrFunction<NumberFieldRenderProps>&#x22;,
            default: &#x22;'react-aria-NumberField'&#x22;,
            description: &#x22;The CSS className for the element.&#x22;,
          },
        }"
    />
  </Accordion>
</Accordions>

Default className: `react-aria-NumberField`

| Render Prop                                               | CSS Selector      |
| :-------------------------------------------------------- | :---------------- |
| `isDisabled` <br /> Whether the number field is disabled. | `[data-disabled]` |
| `isInvalid` <br /> Whether the value is invalid.          | `[data-invalid]`  |


# Popover (/docs/components/popover)





# Popover [#popover]

## Preview [#preview]

<ComponentPreview>
  <PopoverTrigger>
    <Button>
      Trigger Popover
    </Button>

    <Popover>
      <PopoverDialog>
        <div className="p-4 text-sm">
          This is the content inside the popover.
        </div>
      </PopoverDialog>
    </Popover>
  </PopoverTrigger>
</ComponentPreview>

The `Popover` component is built with React Aria and styled using StyleX.

## Import [#import]

```tsx
import { Popover } from '@moul-dev/ui';
```

## Usage [#usage]

Here is a basic example of how to use the `Popover` component:

```tsx
import { Popover } from '@moul-dev/ui';

export default function Example() {
  return (
    <Popover>
      {/* Component content */}
    </Popover>
  );
}
```

## Props [#props]

### Popover Props [#popover-props]

<TypeTable
  type="{
  'showArrow': {
    type: &#x22;boolean&#x22;,
    default: &#x22;true&#x22;,
    description: &#x22;Whether to render a dynamic pointer arrow triangle extending to the trigger.&#x22;,
  },
  'placement': {
    type: &#x22;string&#x22;,
    default: &#x22;'bottom'&#x22;,
    description: &#x22;The placement axis of the popover relative to the trigger.&#x22;,
  },
  'isOpen': {
    type: &#x22;boolean&#x22;,
    description: &#x22;Whether the popover is currently open (controlled).&#x22;,
  },
  'defaultOpen': {
    type: &#x22;boolean&#x22;,
    description: &#x22;Whether the popover is initially open (uncontrolled).&#x22;,
  },
}"
/>

<Accordions>
  <Accordion title="Value">
    <TypeTable
      type="{
          'onOpenChange': {
            type: &#x22;(isOpen: boolean) => void&#x22;,
            description: &#x22;Handler called when open state changes.&#x22;,
          },
        }"
    />
  </Accordion>

  <Accordion title="Styling">
    <TypeTable
      type="{
          'className': {
            type: &#x22;ClassNameOrFunction<PopoverRenderProps>&#x22;,
            default: &#x22;'react-aria-Popover'&#x22;,
            description: &#x22;The CSS className.&#x22;,
          },
        }"
    />
  </Accordion>
</Accordions>

Default className: `react-aria-Popover`

| Render Prop                                  | CSS Selector       |
| :------------------------------------------- | :----------------- |
| `isOpen` <br /> Whether the popover is open. | `[data-open]`      |
| `placement` <br /> The current placement.    | `[data-placement]` |


# RadioGroup (/docs/components/radiogroup)





# RadioGroup [#radiogroup]

## Preview [#preview]

<ComponentPreview>
  <RadioGroup label="Subscription Type">
    <Radio value="free">
      Free
    </Radio>

    <Radio value="pro">
      Pro
    </Radio>

    <Radio value="enterprise">
      Enterprise
    </Radio>
  </RadioGroup>
</ComponentPreview>

The `RadioGroup` component is built with React Aria and styled using StyleX.

## Import [#import]

```tsx
import { RadioGroup } from '@moul-dev/ui';
```

## Usage [#usage]

Here is a basic example of how to use the `RadioGroup` component:

```tsx
import { RadioGroup } from '@moul-dev/ui';

export default function Example() {
  return (
    <RadioGroup>
      {/* Component content */}
    </RadioGroup>
  );
}
```

## Props [#props]

### RadioGroup Props [#radiogroup-props]

<TypeTable
  type="{
  'orientation': {
    type: &#x22;'horizontal' | 'vertical'&#x22;,
    default: &#x22;'vertical'&#x22;,
    description: &#x22;The layout orientation of the radio elements.&#x22;,
  },
  'value': {
    type: &#x22;string&#x22;,
    description: &#x22;The value of the selected radio button (controlled).&#x22;,
  },
  'defaultValue': {
    type: &#x22;string&#x22;,
    description: &#x22;The value of the initially selected radio button (uncontrolled).&#x22;,
  },
  'isDisabled': {
    type: &#x22;boolean&#x22;,
    default: &#x22;false&#x22;,
    description: &#x22;Whether the entire radio group is disabled.&#x22;,
  },
  'isInvalid': {
    type: &#x22;boolean&#x22;,
    description: &#x22;Whether the radio group value is invalid.&#x22;,
  },
}"
/>

<Accordions>
  <Accordion title="Value">
    <TypeTable
      type="{
          'onChange': {
            type: &#x22;(value: string) => void&#x22;,
            description: &#x22;Handler called when the selected value changes.&#x22;,
          },
        }"
    />
  </Accordion>

  <Accordion title="Styling">
    <TypeTable
      type="{
          'className': {
            type: &#x22;ClassNameOrFunction<RadioGroupRenderProps>&#x22;,
            default: &#x22;'react-aria-RadioGroup'&#x22;,
            description: &#x22;The CSS className for the group.&#x22;,
          },
        }"
    />
  </Accordion>
</Accordions>

Default className: `react-aria-RadioGroup`

| Render Prop                                            | CSS Selector      |
| :----------------------------------------------------- | :---------------- |
| `isDisabled` <br /> Whether the group is disabled.     | `[data-disabled]` |
| `isInvalid` <br /> Whether the group value is invalid. | `[data-invalid]`  |


# SearchField (/docs/components/searchfield)





# SearchField [#searchfield]

## Preview [#preview]

<ComponentPreview>
  <SearchField label="Search" placeholder="Type to search..." />
</ComponentPreview>

The `SearchField` component is built with React Aria and styled using StyleX.

## Import [#import]

```tsx
import { SearchField } from '@moul-dev/ui';
```

## Usage [#usage]

Here is a basic example of how to use the `SearchField` component:

```tsx
import { SearchField } from '@moul-dev/ui';

export default function Example() {
  return (
    <SearchField>
      {/* Component content */}
    </SearchField>
  );
}
```

## Props [#props]

### SearchField Props [#searchfield-props]

<TypeTable
  type="{
  'variant': {
    type: &#x22;'primary' | 'secondary'&#x22;,
    default: &#x22;'primary'&#x22;,
    description: &#x22;The visual style variant of the search field.&#x22;,
  },
  'value': {
    type: &#x22;string&#x22;,
    description: &#x22;The current value (controlled).&#x22;,
  },
  'defaultValue': {
    type: &#x22;string&#x22;,
    description: &#x22;The default value (uncontrolled).&#x22;,
  },
  'placeholder': {
    type: &#x22;string&#x22;,
    description: &#x22;Placeholder text inside the input.&#x22;,
  },
  'isDisabled': {
    type: &#x22;boolean&#x22;,
    default: &#x22;false&#x22;,
    description: &#x22;Whether the field is disabled.&#x22;,
  },
}"
/>

<Accordions>
  <Accordion title="Value">
    <TypeTable
      type="{
          'onChange': {
            type: &#x22;(value: string) => void&#x22;,
            description: &#x22;Handler called when the value changes.&#x22;,
          },
          'onSubmit': {
            type: &#x22;(value: string) => void&#x22;,
            description: &#x22;Handler called when the user submits the search query.&#x22;,
          },
          'onClear': {
            type: &#x22;() => void&#x22;,
            description: &#x22;Handler called when the user clears the search field.&#x22;,
          },
        }"
    />
  </Accordion>

  <Accordion title="Styling">
    <TypeTable
      type="{
          'className': {
            type: &#x22;ClassNameOrFunction<SearchFieldRenderProps>&#x22;,
            default: &#x22;'react-aria-SearchField'&#x22;,
            description: &#x22;The CSS className.&#x22;,
          },
        }"
    />
  </Accordion>
</Accordions>

Default className: `react-aria-SearchField`

| Render Prop                                               | CSS Selector      |
| :-------------------------------------------------------- | :---------------- |
| `isDisabled` <br /> Whether the search field is disabled. | `[data-disabled]` |
| `isInvalid` <br /> Whether the search field is invalid.   | `[data-invalid]`  |


# Select (/docs/components/select)





# Select [#select]

## Preview [#preview]

<ComponentPlayground component="Select" />

The `Select` component is built with React Aria and styled using StyleX.

## Import [#import]

```tsx
import { Select } from '@moul-dev/ui';
```

## Usage [#usage]

Here is a basic example of how to use the `Select` component:

```tsx
import { Select } from '@moul-dev/ui';

export default function Example() {
  return (
    <Select>
      {/* Component content */}
    </Select>
  );
}
```

## Props [#props]

### Select Props [#select-props]

<TypeTable
  type="{
  'size': {
    type: &#x22;'sm' | 'md' | 'lg'&#x22;,
    default: &#x22;'md'&#x22;,
    description: &#x22;The size height variant of the selection trigger.&#x22;,
  },
  'selectedKey': {
    type: &#x22;Key&#x22;,
    description: &#x22;The currently selected key (controlled).&#x22;,
  },
  'defaultSelectedKey': {
    type: &#x22;Key&#x22;,
    description: &#x22;The default selected key (uncontrolled).&#x22;,
  },
  'isDisabled': {
    type: &#x22;boolean&#x22;,
    default: &#x22;false&#x22;,
    description: &#x22;Whether selection is disabled.&#x22;,
  },
  'placeholder': {
    type: &#x22;string&#x22;,
    description: &#x22;Placeholder text displayed when no key is selected.&#x22;,
  },
}"
/>

<Accordions>
  <Accordion title="Value">
    <TypeTable
      type="{
          'onSelectionChange': {
            type: &#x22;(key: Key) => void&#x22;,
            description: &#x22;Handler called when selection changes.&#x22;,
          },
        }"
    />
  </Accordion>

  <Accordion title="Styling">
    <TypeTable
      type="{
          'className': {
            type: &#x22;ClassNameOrFunction<SelectRenderProps>&#x22;,
            default: &#x22;'react-aria-Select'&#x22;,
            description: &#x22;The CSS className.&#x22;,
          },
        }"
    />
  </Accordion>
</Accordions>

Default className: `react-aria-Select`

| Render Prop                                                     | CSS Selector           |
| :-------------------------------------------------------------- | :--------------------- |
| `isOpen` <br /> Whether the select popover is open.             | `[data-open]`          |
| `isFocused` <br /> Whether the select is focused.               | `[data-focused]`       |
| `isFocusVisible` <br /> Whether the select is keyboard focused. | `[data-focus-visible]` |
| `isDisabled` <br /> Whether the select is disabled.             | `[data-disabled]`      |


# Separator (/docs/components/separator)





# Separator [#separator]

## Preview [#preview]

<ComponentPreview>
  <div className="flex h-5 items-center space-x-4 text-sm">
    <div>
      Blog
    </div>

    <Separator orientation="vertical" />

    <div>
      Docs
    </div>

    <Separator orientation="vertical" />

    <div>
      Source
    </div>
  </div>
</ComponentPreview>

The `Separator` component is built with React Aria and styled using StyleX.

## Import [#import]

```tsx
import { Separator } from '@moul-dev/ui';
```

## Usage [#usage]

Here is a basic example of how to use the `Separator` component:

```tsx
import { Separator } from '@moul-dev/ui';

export default function Example() {
  return (
    <Separator>
      {/* Component content */}
    </Separator>
  );
}
```

## Props [#props]

### Separator Props [#separator-props]

<TypeTable
  type="{
  'orientation': {
    type: &#x22;'horizontal' | 'vertical'&#x22;,
    default: &#x22;'horizontal'&#x22;,
    description: &#x22;The layout orientation axis of the separator line.&#x22;,
  },
}"
/>

<Accordions>
  <Accordion title="Styling">
    <TypeTable
      type="{
          'className': {
            type: &#x22;string&#x22;,
            description: &#x22;The CSS className.&#x22;,
          },
        }"
    />
  </Accordion>
</Accordions>

Default className: `react-aria-Separator`


# Skeleton (/docs/components/skeleton)





# Skeleton [#skeleton]

## Preview [#preview]

<ComponentPreview>
  <div className="flex items-center space-x-4 w-72">
    <Skeleton className="h-12 w-12 rounded-full" />

    <div className="space-y-2 flex-1">
      <Skeleton className="h-4 w-full" />

      <Skeleton className="h-4 w-5/6" />
    </div>
  </div>
</ComponentPreview>

The `Skeleton` component is built with React Aria and styled using StyleX.

## Import [#import]

```tsx
import { Skeleton } from '@moul-dev/ui';
```

## Usage [#usage]

Here is a basic example of how to use the `Skeleton` component:

```tsx
import { Skeleton } from '@moul-dev/ui';

export default function Example() {
  return (
    <Skeleton>
      {/* Component content */}
    </Skeleton>
  );
}
```


# Slider (/docs/components/slider)





# Slider [#slider]

## Preview [#preview]

<ComponentPlayground component="Slider" />

The `Slider` component is built with React Aria and styled using StyleX.

## Import [#import]

```tsx
import { Slider } from '@moul-dev/ui';
```

## Usage [#usage]

Here is a basic example of how to use the `Slider` component:

```tsx
import { Slider } from '@moul-dev/ui';

export default function Example() {
  return (
    <Slider>
      {/* Component content */}
    </Slider>
  );
}
```

## Props [#props]

### Slider Props [#slider-props]

<TypeTable
  type="{
  'value': {
    type: &#x22;number | number[]&#x22;,
    description: &#x22;The current value (controlled).&#x22;,
  },
  'defaultValue': {
    type: &#x22;number | number[]&#x22;,
    description: &#x22;The default value (uncontrolled).&#x22;,
  },
  'minValue': {
    type: &#x22;number&#x22;,
    default: &#x22;0&#x22;,
    description: &#x22;The minimum allowed value.&#x22;,
  },
  'maxValue': {
    type: &#x22;number&#x22;,
    default: &#x22;100&#x22;,
    description: &#x22;The maximum allowed value.&#x22;,
  },
  'step': {
    type: &#x22;number&#x22;,
    default: &#x22;1&#x22;,
    description: &#x22;The granularity of step values.&#x22;,
  },
  'isDisabled': {
    type: &#x22;boolean&#x22;,
    default: &#x22;false&#x22;,
    description: &#x22;Whether interaction is disabled.&#x22;,
  },
  'orientation': {
    type: &#x22;'horizontal' | 'vertical'&#x22;,
    default: &#x22;'horizontal'&#x22;,
    description: &#x22;The layout orientation of the slider track.&#x22;,
  },
}"
/>

<Accordions>
  <Accordion title="Value">
    <TypeTable
      type="{
          'onChange': {
            type: &#x22;(value: number | number[]) => void&#x22;,
            description: &#x22;Handler called when value changes.&#x22;,
          },
          'onChangeEnd': {
            type: &#x22;(value: number | number[]) => void&#x22;,
            description: &#x22;Handler called when interaction ends.&#x22;,
          },
        }"
    />
  </Accordion>

  <Accordion title="Styling">
    <TypeTable
      type="{
          'className': {
            type: &#x22;ClassNameOrFunction<SliderRenderProps>&#x22;,
            default: &#x22;'react-aria-Slider'&#x22;,
            description: &#x22;The CSS className.&#x22;,
          },
        }"
    />
  </Accordion>
</Accordions>

Default className: `react-aria-Slider`

| Render Prop                                         | CSS Selector         |
| :-------------------------------------------------- | :------------------- |
| `isDisabled` <br /> Whether the slider is disabled. | `[data-disabled]`    |
| `orientation` <br /> The orientation of the slider. | `[data-orientation]` |


# Spinner (/docs/components/spinner)





# Spinner [#spinner]

## Preview [#preview]

<ComponentPreview>
  <Spinner />
</ComponentPreview>

The `Spinner` component is built with React Aria and styled using StyleX.

## Import [#import]

```tsx
import { Spinner } from '@moul-dev/ui';
```

## Usage [#usage]

Here is a basic example of how to use the `Spinner` component:

```tsx
import { Spinner } from '@moul-dev/ui';

export default function Example() {
  return (
    <Spinner>
      {/* Component content */}
    </Spinner>
  );
}
```


# Switch (/docs/components/switch)





# Switch [#switch]

## Preview [#preview]

<ComponentPlayground component="Switch" />

The `Switch` component is built with React Aria and styled using StyleX.

## Import [#import]

```tsx
import { Switch } from '@moul-dev/ui';
```

## Usage [#usage]

Here is a basic example of how to use the `Switch` component:

```tsx
import { Switch } from '@moul-dev/ui';

export default function Example() {
  return (
    <Switch>
      {/* Component content */}
    </Switch>
  );
}
```

## Props [#props]

### Switch Props [#switch-props]

<TypeTable
  type="{
  'isSelected': {
    type: &#x22;boolean&#x22;,
    description: &#x22;Whether the switch is selected (controlled).&#x22;,
  },
  'defaultSelected': {
    type: &#x22;boolean&#x22;,
    description: &#x22;Whether the switch is selected by default (uncontrolled).&#x22;,
  },
  'isDisabled': {
    type: &#x22;boolean&#x22;,
    default: &#x22;false&#x22;,
    description: &#x22;Whether the switch is disabled.&#x22;,
  },
  'isReadOnly': {
    type: &#x22;boolean&#x22;,
    description: &#x22;Whether the switch is read-only.&#x22;,
  },
}"
/>

<Accordions>
  <Accordion title="Value">
    <TypeTable
      type="{
          'onChange': {
            type: &#x22;(isSelected: boolean) => void&#x22;,
            description: &#x22;Handler called when the selection state changes.&#x22;,
          },
        }"
    />
  </Accordion>

  <Accordion title="Styling">
    <TypeTable
      type="{
          'className': {
            type: &#x22;ClassNameOrFunction<SwitchRenderProps>&#x22;,
            default: &#x22;'react-aria-Switch'&#x22;,
            description: &#x22;The CSS className for the element.&#x22;,
          },
        }"
    />
  </Accordion>
</Accordions>

Default className: `react-aria-Switch`

| Render Prop                                                     | CSS Selector           |
| :-------------------------------------------------------------- | :--------------------- |
| `isSelected` <br /> Whether the switch is checked.              | `[data-selected]`      |
| `isHovered` <br /> Whether the switch is hovered.               | `[data-hovered]`       |
| `isPressed` <br /> Whether the switch is pressed.               | `[data-pressed]`       |
| `isFocused` <br /> Whether the switch is focused.               | `[data-focused]`       |
| `isFocusVisible` <br /> Whether the switch is keyboard focused. | `[data-focus-visible]` |
| `isDisabled` <br /> Whether the switch is disabled.             | `[data-disabled]`      |
| `isReadOnly` <br /> Whether the switch is read-only.            | `[data-readonly]`      |


# Table (/docs/components/table)





# Table [#table]

## Preview [#preview]

<ComponentPreview>
  <Table aria-label="Simple Table" className="border border-neutral-200 dark:border-neutral-800 rounded-lg overflow-hidden w-96">
    <TableHeader>
      <Column>
        Name
      </Column>

      <Column>
        Type
      </Column>

      <Column>
        Status
      </Column>
    </TableHeader>

    <TableBody>
      <Row>
        <Cell>
          Button
        </Cell>

        <Cell>
          Action
        </Cell>

        <Cell>
          Stable
        </Cell>
      </Row>

      <Row>
        <Cell>
          Select
        </Cell>

        <Cell>
          Form
        </Cell>

        <Cell>
          Beta
        </Cell>
      </Row>
    </TableBody>
  </Table>
</ComponentPreview>

The `Table` component is built with React Aria and styled using StyleX.

## Import [#import]

```tsx
import { Table } from '@moul-dev/ui';
```

## Usage [#usage]

Here is a basic example of how to use the `Table` component:

```tsx
import { Table } from '@moul-dev/ui';

export default function Example() {
  return (
    <Table>
      {/* Component content */}
    </Table>
  );
}
```

## Props [#props]

### Table Props [#table-props]

<TypeTable
  type="{
  'selectionMode': {
    type: &#x22;'none' | 'single' | 'multiple'&#x22;,
    default: &#x22;'none'&#x22;,
    description: &#x22;The selection mode permitted.&#x22;,
  },
}"
/>

<Accordions>
  <Accordion title="Value">
    <TypeTable
      type="{
          'onSelectionChange': {
            type: &#x22;(keys: 'all' | Set<Key>) => void&#x22;,
            description: &#x22;Fires when row selection changes.&#x22;,
          },
        }"
    />
  </Accordion>

  <Accordion title="Styling">
    <TypeTable
      type="{
          'className': {
            type: &#x22;string&#x22;,
            description: &#x22;The CSS className.&#x22;,
          },
        }"
    />
  </Accordion>
</Accordions>

Default className: `react-aria-Table`


# Tabs (/docs/components/tabs)





# Tabs [#tabs]

Tabs organize content into multiple sections and allow users to navigate between them. It is built using React Aria Components and styled compile-time using StyleX, featuring smooth selection sliding indicator animations.

## Preview [#preview]

<ComponentPreview>
  <Tabs className="w-80" defaultValue="profile">
    <TabList aria-label="Settings Tabs">
      <Tab id="profile">
        Profile
      </Tab>

      <Tab id="notifications">
        Notifications
      </Tab>

      <Tab id="security">
        Security
      </Tab>
    </TabList>

    <TabPanels>
      <TabPanel id="profile">
        Profile settings and account parameters.
      </TabPanel>

      <TabPanel id="notifications">
        Configure email and push notification preferences.
      </TabPanel>

      <TabPanel id="security">
        Manage password, two-factor authentication, and active sessions.
      </TabPanel>
    </TabPanels>
  </Tabs>
</ComponentPreview>

## Import [#import]

```tsx
import { Tabs, TabList, Tab, TabPanels, TabPanel } from '@moul-dev/ui';
```

## Variants [#variants]

The `Tabs` component supports three visual variants through the `variant` prop: `primary` (default brand indicator), `secondary` (foreground indicator), and `tertiary` (sliding pill background bubble).

### Primary (Default) [#primary-default]

The primary variant uses the brand accent color for the selection indicator underline.

```tsx
<Tabs variant="primary">
  <TabList aria-label="Primary Tabs">
    <Tab id="1">Tab 1</Tab>
    <Tab id="2">Tab 2</Tab>
  </TabList>
  <TabPanels>
    <TabPanel id="1">Content 1</TabPanel>
    <TabPanel id="2">Content 2</TabPanel>
  </TabPanels>
</Tabs>
```

### Secondary [#secondary]

The secondary variant uses the default foreground text color for the selection indicator underline.

<ComponentPreview>
  <Tabs variant="secondary" className="w-80" defaultValue="1">
    <TabList aria-label="Secondary Tabs">
      <Tab id="1">
        Tab 1
      </Tab>

      <Tab id="2">
        Tab 2
      </Tab>
    </TabList>

    <TabPanels>
      <TabPanel id="1">
        Secondary variant content 1
      </TabPanel>

      <TabPanel id="2">
        Secondary variant content 2
      </TabPanel>
    </TabPanels>
  </Tabs>
</ComponentPreview>

### Tertiary (Sliding Pill) [#tertiary-sliding-pill]

The tertiary variant renders a premium sliding rounded pill background under the selected tab and removes borders from the tab list.

<ComponentPreview>
  <Tabs variant="tertiary" className="w-80" defaultValue="1">
    <TabList aria-label="Tertiary Tabs">
      <Tab id="1">
        Tab 1
      </Tab>

      <Tab id="2">
        Tab 2
      </Tab>

      <Tab id="3">
        Tab 3
      </Tab>
    </TabList>

    <TabPanels>
      <TabPanel id="1">
        Pill style layout content 1
      </TabPanel>

      <TabPanel id="2">
        Pill style layout content 2
      </TabPanel>

      <TabPanel id="3">
        Pill style layout content 3
      </TabPanel>
    </TabPanels>
  </Tabs>
</ComponentPreview>

## Vertical Orientation [#vertical-orientation]

Tabs can be stacked vertically using the `orientation="vertical"` prop. The selection indicator animates along the vertical axis, and the tab panels are laid out inline to the right.

<ComponentPreview>
  <Tabs orientation="vertical" variant="primary" className="w-full max-w-md" defaultValue="general">
    <TabList aria-label="Settings categories">
      <Tab id="general">
        General
      </Tab>

      <Tab id="appearance">
        Appearance
      </Tab>

      <Tab id="security">
        Security
      </Tab>
    </TabList>

    <TabPanels>
      <TabPanel id="general">
        General account settings configuration.
      </TabPanel>

      <TabPanel id="appearance">
        Customize themes, dark mode, font sizes, and layout choices.
      </TabPanel>

      <TabPanel id="security">
        Manage active authentication keys and access logs.
      </TabPanel>
    </TabPanels>
  </Tabs>
</ComponentPreview>

## Props [#props]

### Tabs Props [#tabs-props]

<TypeTable
  type="{
  'variant': {
    type: &#x22;'primary' | 'secondary' | 'tertiary'&#x22;,
    default: &#x22;'primary'&#x22;,
    description: &#x22;The visual style design of the active tab indicator.&#x22;,
  },
  'orientation': {
    type: &#x22;'horizontal' | 'vertical'&#x22;,
    default: &#x22;'horizontal'&#x22;,
    description: &#x22;The layout axis direction of the tabs.&#x22;,
  },
  'selectedKey': {
    type: &#x22;Key&#x22;,
    description: &#x22;The selected tab key (controlled).&#x22;,
  },
  'defaultSelectedKey': {
    type: &#x22;Key&#x22;,
    description: &#x22;The default selected tab key (uncontrolled).&#x22;,
  },
  'isDisabled': {
    type: &#x22;boolean&#x22;,
    default: &#x22;false&#x22;,
    description: &#x22;Whether all tabs are disabled.&#x22;,
  },
}"
/>

<Accordions>
  <Accordion title="Value">
    <TypeTable
      type="{
          'onSelectionChange': {
            type: &#x22;(key: Key) => void&#x22;,
            description: &#x22;Handler called when active tab selection changes.&#x22;,
          },
        }"
    />
  </Accordion>

  <Accordion title="Styling">
    <TypeTable
      type="{
          'className': {
            type: &#x22;ClassNameOrFunction<TabsRenderProps>&#x22;,
            default: &#x22;'react-aria-Tabs'&#x22;,
            description: &#x22;The CSS className.&#x22;,
          },
        }"
    />
  </Accordion>
</Accordions>

Default className: `react-aria-Tabs`

| Render Prop                                            | CSS Selector         |
| :----------------------------------------------------- | :------------------- |
| `orientation` <br /> The layout orientation.           | `[data-orientation]` |
| `isDisabled` <br /> Whether the component is disabled. | `[data-disabled]`    |


# TagGroup (/docs/components/taggroup)





# TagGroup [#taggroup]

A tag group is a focusable list of labels, categories, keywords, filters, or other items, with support for keyboard navigation, selection, and removal.

## Preview [#preview]

<ComponentPlayground component="TagGroup" />

The `TagGroup` component is built with React Aria and styled using StyleX.

## Import [#import]

```tsx
import { TagGroup, Tag } from '@moul-dev/ui';
```

## Usage [#usage]

Here is a basic example of how to use the `TagGroup` component:

```tsx
import { TagGroup, Tag } from '@moul-dev/ui';

export default function Example() {
  return (
    <TagGroup label="Categories">
      <Tag>News</Tag>
      <Tag>Travel</Tag>
      <Tag>Gaming</Tag>
      <Tag>Shopping</Tag>
    </TagGroup>
  );
}
```

## Variants [#variants]

TagGroup and Tag support three variants: `primary`, `secondary` (default), and `tertiary`. You can pass the variant to the `TagGroup` to apply it to all tags, or override it on individual `Tag`s.

```tsx
<TagGroup label="Primary Tags" variant="primary">
  <Tag>Analytics</Tag>
  <Tag>Security</Tag>
</TagGroup>

<TagGroup label="Secondary Tags" variant="secondary">
  <Tag>Analytics</Tag>
  <Tag>Security</Tag>
</TagGroup>

<TagGroup label="Tertiary Tags" variant="tertiary">
  <Tag>Analytics</Tag>
  <Tag>Security</Tag>
</TagGroup>
```

## Sizes [#sizes]

TagGroup and Tag support three sizes: `sm`, `md` (default), and `lg`. You can set the size on the `TagGroup` to apply it to all tags, or override it on individual `Tag`s.

```tsx
<TagGroup label="Small" size="sm">
  <Tag>Small tag</Tag>
</TagGroup>

<TagGroup label="Medium" size="md">
  <Tag>Medium tag</Tag>
</TagGroup>

<TagGroup label="Large" size="lg">
  <Tag>Large tag</Tag>
</TagGroup>
```

## Selection [#selection]

Use the `selectionMode` prop to enable single or multiple selection.

```tsx
import { TagGroup, Tag } from '@moul-dev/ui';
import { useState } from 'react';
import type { Selection } from 'react-aria-components';

export default function Example() {
  const [selected, setSelected] = useState<Selection>(new Set(['news']));

  return (
    <TagGroup
      label="Categories"
      selectionMode="multiple"
      selectedKeys={selected}
      onSelectionChange={setSelected}
    >
      <Tag id="news">News</Tag>
      <Tag id="travel">Travel</Tag>
      <Tag id="gaming">Gaming</Tag>
    </TagGroup>
  );
}
```

## Removal [#removal]

Pass an `onRemove` callback to the `TagGroup` component to allow items to be removed. When specified, tags will automatically render close buttons suited to their sizes and variants.

```tsx
import { TagGroup, Tag } from '@moul-dev/ui';
import { useState } from 'react';

export default function Example() {
  const [tags, setTags] = useState([
    { id: '1', label: 'News' },
    { id: '2', label: 'Travel' },
    { id: '3', label: 'Gaming' },
  ]);

  const handleRemove = (keys) => {
    setTags((prev) => prev.filter((tag) => !keys.has(tag.id)));
  };

  return (
    <TagGroup label="Categories" onRemove={handleRemove}>
      {tags.map((tag) => (
        <Tag key={tag.id} id={tag.id}>
          {tag.label}
        </Tag>
      ))}
    </TagGroup>
  );
}
```

## Props [#props]

### TagGroup Props [#taggroup-props]

<TypeTable
  type="{
  'size': {
    type: &#x22;'sm' | 'md'&#x22;,
    default: &#x22;'md'&#x22;,
    description: &#x22;The size of child tags.&#x22;,
  },
  'variant': {
    type: &#x22;'primary' | 'secondary' | 'quiet'&#x22;,
    default: &#x22;'secondary'&#x22;,
    description: &#x22;The visual style variant of child tags.&#x22;,
  },
  'selectionMode': {
    type: &#x22;'none' | 'single' | 'multiple'&#x22;,
    default: &#x22;'none'&#x22;,
    description: &#x22;The selection mode allowed.&#x22;,
  },
  'selectedKeys': {
    type: &#x22;'all' | Iterable<Key>&#x22;,
    description: &#x22;The selected tag keys (controlled).&#x22;,
  },
  'defaultSelectedKeys': {
    type: &#x22;'all' | Iterable<Key>&#x22;,
    description: &#x22;The initially selected tag keys (uncontrolled).&#x22;,
  },
  'isDisabled': {
    type: &#x22;boolean&#x22;,
    default: &#x22;false&#x22;,
    description: &#x22;Whether selection is disabled.&#x22;,
  },
}"
/>

<Accordions>
  <Accordion title="Value">
    <TypeTable
      type="{
          'onSelectionChange': {
            type: &#x22;(keys: 'all' | Set<Key>) => void&#x22;,
            description: &#x22;Handler called when selection changes.&#x22;,
          },
          'onRemove': {
            type: &#x22;(keys: Set<Key>) => void&#x22;,
            description: &#x22;Handler called when a tag is dismissed.&#x22;,
          },
        }"
    />
  </Accordion>

  <Accordion title="Styling">
    <TypeTable
      type="{
          'className': {
            type: &#x22;string&#x22;,
            description: &#x22;The CSS className.&#x22;,
          },
        }"
    />
  </Accordion>
</Accordions>

Default className: `react-aria-TagGroup`


# TextArea (/docs/components/textarea)





<div style="{ display: 'none' }">
  Label, Description, FieldError, ErrorMessage, Helper Text, Validation, Error Message, Input Label
</div>

# TextArea [#textarea]

## Preview [#preview]

<ComponentPreview>
  <TextArea label="Bio" placeholder="Tell us about yourself..." description="Must be under 200 words." className="w-80" />
</ComponentPreview>

The `TextArea` component is built with React Aria and styled using StyleX. It automatically handles layout composition for label, description, and validation error messages.

## Import [#import]

```tsx
import { TextArea } from '@moul-dev/ui';
```

## Features [#features]

### Label [#label]

The text area automatically renders an accessible `<Label>` element above the text area input when the `label` prop is provided.

<ComponentPreview>
  <TextArea label="Bio" placeholder="Tell us about yourself..." className="w-80" />
</ComponentPreview>

```tsx
<TextArea label="Bio" placeholder="Tell us about yourself..." />
```

### Description [#description]

Use the `description` prop to display help text or guidelines below the text area input. This automatically wires up accessibility relationships so assistive technologies can read it.

<ComponentPreview>
  <TextArea label="Comments" description="Please do not include sensitive personal information." className="w-80" />
</ComponentPreview>

```tsx
<TextArea
  label="Comments"
  description="Please do not include sensitive personal information."
/>
```

### Validation & FieldError [#validation--fielderror]

If the input is invalid, you can provide an error message using the `errorMessage` prop. This renders a `<FieldError>` component automatically when the field validation fails.

<ComponentPreview>
  <TextArea label="Message" errorMessage="Please enter your message." className="w-80" />
</ComponentPreview>

```tsx
<TextArea
  label="Message"
  isRequired
  isInvalid
  errorMessage="Please enter your message."
/>
```

#### Standalone ErrorMessage [#standalone-errormessage]

For manual or custom validation outside of the built-in `errorMessage` prop, you can import and render the standalone `<ErrorMessage>` component.

<ComponentPreview>
  <ErrorMessage>
    Invalid input description.
  </ErrorMessage>
</ComponentPreview>

```tsx
import { ErrorMessage } from '@moul-dev/ui';

<ErrorMessage>Invalid input description.</ErrorMessage>
```

## Usage [#usage]

Here is a basic example of a configured `TextArea`:

```tsx
import { TextArea } from '@moul-dev/ui';

export default function Example() {
  return (
    <TextArea
      label="Description"
      placeholder="Briefly describe your project..."
      description="Max 500 characters."
      isRequired
      errorMessage="A description is required."
    />
  );
}
```

## Props [#props]

### TextArea Props [#textarea-props]

<TypeTable
  type="{
  'variant': {
    type: &#x22;'primary' | 'secondary'&#x22;,
    default: &#x22;'primary'&#x22;,
    description: &#x22;The visual style variant of the textarea.&#x22;,
  },
  'rows': {
    type: &#x22;number&#x22;,
    default: &#x22;3&#x22;,
    description: &#x22;The number of visible text lines.&#x22;,
  },
  'value': {
    type: &#x22;string&#x22;,
    description: &#x22;The current value of the textarea (controlled).&#x22;,
  },
  'defaultValue': {
    type: &#x22;string&#x22;,
    description: &#x22;The default value of the textarea (uncontrolled).&#x22;,
  },
  'placeholder': {
    type: &#x22;string&#x22;,
    description: &#x22;Temporary placeholder text.&#x22;,
  },
  'isDisabled': {
    type: &#x22;boolean&#x22;,
    default: &#x22;false&#x22;,
    description: &#x22;Whether the textarea is disabled.&#x22;,
  },
  'isReadOnly': {
    type: &#x22;boolean&#x22;,
    description: &#x22;Whether the textarea is read-only.&#x22;,
  },
}"
/>

<Accordions>
  <Accordion title="Value">
    <TypeTable
      type="{
          'onChange': {
            type: &#x22;(value: string) => void&#x22;,
            description: &#x22;Handler called when the value changes.&#x22;,
          },
        }"
    />
  </Accordion>

  <Accordion title="Styling">
    <TypeTable
      type="{
          'className': {
            type: &#x22;string&#x22;,
            description: &#x22;The CSS className for the container.&#x22;,
          },
        }"
    />
  </Accordion>
</Accordions>

Default className: `react-aria-TextField`


# TextField (/docs/components/textfield)





<div style="{ display: 'none' }">
  Label, Description, FieldError, ErrorMessage, Helper Text, Validation, Error Message, Input Label
</div>

# TextField [#textfield]

## Preview [#preview]

<ComponentPlayground component="TextField" />

The `TextField` component is built with React Aria and styled using StyleX. It automatically handles layout composition for label, description, and validation error messages.

## Import [#import]

```tsx
import { TextField } from '@moul-dev/ui';
```

## Features [#features]

### Label [#label]

The text field automatically renders an accessible `<Label>` element above the input when the `label` prop is provided.

<ComponentPreview>
  <TextField label="Full Name" placeholder="John Doe" className="w-80" />
</ComponentPreview>

```tsx
<TextField label="Full Name" placeholder="John Doe" />
```

### Description [#description]

Use the `description` prop to display help text or guidelines below the input field. This automatically wires up accessibility relationships so assistive technologies can read it.

<ComponentPreview>
  <TextField label="Password" type="password" description="Must be at least 8 characters long." className="w-80" />
</ComponentPreview>

```tsx
<TextField
  label="Password"
  type="password"
  description="Must be at least 8 characters long."
/>
```

### Validation & FieldError [#validation--fielderror]

If the input is invalid, you can provide an error message using the `errorMessage` prop. This renders a `<FieldError>` component automatically when the field validation fails.

<ComponentPreview>
  <TextField label="Email" type="email" errorMessage="Please enter a valid email address." className="w-80" />
</ComponentPreview>

```tsx
<TextField
  label="Email"
  type="email"
  isRequired
  isInvalid
  errorMessage="Please enter a valid email address."
/>
```

#### Standalone ErrorMessage [#standalone-errormessage]

For manual or custom validation outside of the built-in `errorMessage` prop, you can import and render the standalone `<ErrorMessage>` component.

<ComponentPreview>
  <ErrorMessage>
    Invalid email address format.
  </ErrorMessage>
</ComponentPreview>

```tsx
import { ErrorMessage } from '@moul-dev/ui';

<ErrorMessage>Invalid email address format.</ErrorMessage>
```

## Usage [#usage]

Here is a basic example of a configured `TextField`:

```tsx
import { TextField } from '@moul-dev/ui';

export default function Example() {
  return (
    <TextField
      label="Username"
      placeholder="e.g. janesmith"
      description="Your unique handle on the platform."
      isRequired
      errorMessage="Username is required."
    />
  );
}
```

## Props [#props]

### TextField Props [#textfield-props]

<TypeTable
  type="{
  'variant': {
    type: &#x22;'primary' | 'secondary'&#x22;,
    default: &#x22;'primary'&#x22;,
    description: &#x22;The visual style variant of the input field.&#x22;,
  },
  'size': {
    type: &#x22;'sm' | 'md' | 'lg'&#x22;,
    default: &#x22;'md'&#x22;,
    description: &#x22;The vertical height size of the input field.&#x22;,
  },
  'value': {
    type: &#x22;string&#x22;,
    description: &#x22;The current value of the input (controlled).&#x22;,
  },
  'defaultValue': {
    type: &#x22;string&#x22;,
    description: &#x22;The default value of the input (uncontrolled).&#x22;,
  },
  'placeholder': {
    type: &#x22;string&#x22;,
    description: &#x22;Temporary placeholder text displayed when the input is empty.&#x22;,
  },
  'isDisabled': {
    type: &#x22;boolean&#x22;,
    default: &#x22;false&#x22;,
    description: &#x22;Whether the text field is disabled.&#x22;,
  },
  'isReadOnly': {
    type: &#x22;boolean&#x22;,
    description: &#x22;Whether the text field is read-only.&#x22;,
  },
  'isInvalid': {
    type: &#x22;boolean&#x22;,
    description: &#x22;Whether the input value is invalid.&#x22;,
  },
}"
/>

<Accordions>
  <Accordion title="Value">
    <TypeTable
      type="{
          'onChange': {
            type: &#x22;(value: string) => void&#x22;,
            description: &#x22;Handler called when the input value changes.&#x22;,
          },
        }"
    />
  </Accordion>

  <Accordion title="Styling">
    <TypeTable
      type="{
          'className': {
            type: &#x22;ClassNameOrFunction<TextFieldRenderProps>&#x22;,
            default: &#x22;'react-aria-TextField'&#x22;,
            description: &#x22;The CSS className for the element.&#x22;,
          },
        }"
    />
  </Accordion>
</Accordions>

Default className: `react-aria-TextField`

| Render Prop                                             | CSS Selector      |
| :------------------------------------------------------ | :---------------- |
| `isDisabled` <br /> Whether the text field is disabled. | `[data-disabled]` |
| `isInvalid` <br /> Whether the input is invalid.        | `[data-invalid]`  |


# Toast (/docs/components/toast)





# Toast [#toast]

## Preview [#preview]

<ComponentPlayground component="Toast" />

The `Toast` component is built with React Aria and styled using StyleX. Multiple active toasts are stacked vertically with elegant y-spacing.

## Import [#import]

To use toast notifications in your application, you need to import the hooks and the container component:

```tsx
import { useToast, ToastContainer } from '@moul-dev/ui';
```

## Usage [#usage]

Place the `ToastContainer` at the root of your application (or near the layout root), and call the `useToast` hook to trigger notifications:

```tsx
import { useToast, ToastContainer, Button } from '@moul-dev/ui';

export default function Example() {
  const toast = useToast();

  return (
    <div>
      <Button onPress={() => toast.show('Hello World!')}>
        Show Toast
      </Button>
      
      {/* ToastContainer must be rendered to display the active toasts */}
      <ToastContainer />
    </div>
  );
}
```

## Options & Variants [#options--variants]

The `toast.show` function accepts a title string as the first argument, and an optional options object as the second:

```typescript
toast.show(title: string, options?: {
  description?: string;
  variant?: 'info' | 'success' | 'warning' | 'error';
  timeout?: number; // duration in ms, default is 5000
});
```

### Examples [#examples]

#### Success Notification [#success-notification]

```typescript
toast.show('Action Completed', {
  description: 'Your changes have been saved.',
  variant: 'success',
});
```

#### Error Notification [#error-notification]

```typescript
toast.show('Request Failed', {
  description: 'Could not connect to server.',
  variant: 'error',
  timeout: 8000,
});
```

#### Warning Notification [#warning-notification]

```typescript
toast.show('Unsaved Changes', {
  description: 'Please review your updates.',
  variant: 'warning',
});
```

## Props [#props]

### Toast Props [#toast-props]

<TypeTable
  type="{
  'toast': {
    type: &#x22;ToastState&#x22;,
    description: &#x22;The active single toast queue item reference.&#x22;,
  },
}"
/>

<Accordions>
  <Accordion title="Styling">
    <TypeTable
      type="{
          'className': {
            type: &#x22;string&#x22;,
            description: &#x22;The CSS className.&#x22;,
          },
        }"
    />
  </Accordion>
</Accordions>

Default className: `react-aria-Toast`


# ToggleButton (/docs/components/togglebutton)





# ToggleButton [#togglebutton]

A toggle button allows a user to toggle a selection on or off, for example switching between two states or modes.

## Preview [#preview]

<ComponentPlayground component="ToggleButton" />

The `ToggleButton` component is built with React Aria and styled using StyleX.

## Import [#import]

```tsx
import { ToggleButton } from '@moul-dev/ui';
```

## Variants [#variants]

You can customize the styling variant of the toggle button using the `variant` prop:

<ComponentPreview>
  <div className="flex gap-4 items-center">
    <ToggleButton variant="primary">
      Primary
    </ToggleButton>

    <ToggleButton variant="secondary">
      Secondary
    </ToggleButton>
  </div>
</ComponentPreview>

```tsx
<ToggleButton variant="primary">Primary</ToggleButton>
<ToggleButton variant="secondary">Secondary</ToggleButton>
```

## Sizes [#sizes]

You can customize the size of the toggle button using the `size` prop:

<ComponentPreview>
  <div className="flex gap-4 items-center">
    <ToggleButton size="sm">
      Small
    </ToggleButton>

    <ToggleButton size="md">
      Medium (Default)
    </ToggleButton>

    <ToggleButton size="lg">
      Large
    </ToggleButton>
  </div>
</ComponentPreview>

```tsx
<ToggleButton size="sm">Small</ToggleButton>
<ToggleButton size="md">Medium (Default)</ToggleButton>
<ToggleButton size="lg">Large</ToggleButton>
```

## Selection [#selection]

Use the `isSelected` or `defaultSelected` prop to set the selection state, and `onChange` to handle selection changes.

```tsx
import { useState } from 'react';
import { ToggleButton } from '@moul-dev/ui';
import { Star } from 'lucide-react';

function Example(props) {
  let [selected, setSelection] = useState(false);

  return (
    <>
      <ToggleButton
        {...props}
        aria-label="Star"
        isSelected={selected}
        onChange={setSelection}>
        <Star size={18} />
      </ToggleButton>
      <p>{selected ? 'Starred' : 'Not starred'}</p>
    </>
  );
}
```

## Props [#props]

### ToggleButton Props [#togglebutton-props]

<TypeTable
  type="{
  id: {
    type: 'Key',
    description: 'When used in a ToggleButtonGroup, an identifier for the item in selectedKeys. When used standalone, a DOM id.',
  },
  isSelected: {
    type: 'boolean',
    description: 'Whether the element should be selected (controlled).',
  },
  defaultSelected: {
    type: 'boolean',
    description: 'Whether the element should be selected (uncontrolled).',
  },
  isDisabled: {
    type: 'boolean',
    description: 'Whether the button is disabled.',
  },
  children: {
    type: 'ChildrenOrFunction<ToggleButtonRenderProps>',
    description: 'The children of the component. A function may be provided to alter the children based on component state.',
  },
  size: {
    type: &#x22;'sm' | 'md' | 'lg'&#x22;,
    default: &#x22;'md'&#x22;,
    description: 'The size of the button.',
  },
  variant: {
    type: &#x22;'primary' | 'secondary'&#x22;,
    default: &#x22;'primary'&#x22;,
    description: 'The variant style of the button.',
  },
  isSquare: {
    type: 'boolean',
    default: 'false',
    description: 'Whether the button should be a square, matching height and width with even padding.',
  },
}"
/>

<Accordions>
  <Accordion title="Value">
    <TypeTable
      type="{
      onChange: {
        type: '(isSelected: boolean) => void',
        description: &#x22;Handler that is called when the element's selection state changes.&#x22;,
      },
    }"
    />
  </Accordion>

  <Accordion title="Events">
    <TypeTable
      type="{
      onPress: {
        type: '(e: PressEvent) => void',
        description: 'Handler that is called when the press is released over the target.',
      },
      onPressStart: {
        type: '(e: PressEvent) => void',
        description: 'Handler that is called when a press interaction starts.',
      },
      onPressEnd: {
        type: '(e: PressEvent) => void',
        description: 'Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target.',
      },
      onPressChange: {
        type: '(isPressed: boolean) => void',
        description: 'Handler that is called when the press state changes.',
      },
      onPressUp: {
        type: '(e: PressEvent) => void',
        description: 'Handler that is called when a press is released over the target, regardless of whether it started on the target or not.',
      },
      onHoverStart: {
        type: '(e: HoverEvent) => void',
        description: 'Handler that is called when a hover interaction starts.',
      },
      onHoverEnd: {
        type: '(e: HoverEvent) => void',
        description: 'Handler that is called when a hover interaction ends.',
      },
      onHoverChange: {
        type: '(isHovering: boolean) => void',
        description: 'Handler that is called when the hover state changes.',
      },
      onFocus: {
        type: '(e: FocusEvent) => void',
        description: 'Handler that is called when the element receives focus.',
      },
      onBlur: {
        type: '(e: FocusEvent) => void',
        description: 'Handler that is called when the element loses focus.',
      },
      onFocusChange: {
        type: '(isFocused: boolean) => void',
        description: &#x22;Handler that is called when the element's focus status changes.&#x22;,
      },
      onKeyDown: {
        type: '(e: KeyboardEvent) => void',
        description: 'Handler that is called when a key is pressed.',
      },
      onKeyUp: {
        type: '(e: KeyboardEvent) => void',
        description: 'Handler that is called when a key is released.',
      },
      onClick: {
        type: '(e: MouseEvent) => void',
        description: '**Not recommended – use onPress instead.** onClick is an alias for onPress provided for compatibility with other libraries. onPress provides additional event details for non-mouse interactions.',
      },
    }"
    />
  </Accordion>

  <Accordion title="Styling">
    <TypeTable
      type="{
      className: {
        type: 'ClassNameOrFunction<ToggleButtonRenderProps>',
        default: &#x22;'react-aria-ToggleButton'&#x22;,
        description: 'The CSS className for the element. A function may be provided to compute the class based on component state.',
      },
      style: {
        type: 'CSSProperties | ((values: ToggleButtonRenderProps & { defaultStyle: CSSProperties }) => CSSProperties)',
        description: 'The inline style for the element. A function may be provided to compute the style based on component state.',
      },
      render: {
        type: 'DOMRenderFunction<&#x22;button&#x22;, ToggleButtonRenderProps>',
        description: 'Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components.',
      },
    }"
    />
  </Accordion>

  <Accordion title="Accessibility">
    <TypeTable
      type="{
      'aria-label': {
        type: 'string',
        description: 'Defines a string value that labels the current element.',
      },
      'aria-labelledby': {
        type: 'string',
        description: 'Identifies the element (or elements) that labels the current element.',
      },
      'aria-describedby': {
        type: 'string',
        description: 'Identifies the element (or elements) that describes the object.',
      },
      'aria-details': {
        type: 'string',
        description: 'Identifies the element (or elements) that provide a detailed, extended description for the object.',
      },
      'aria-pressed': {
        type: 'boolean | &#x22;true&#x22; | &#x22;false&#x22; | &#x22;mixed&#x22;',
        description: 'Indicates the current &#x22;pressed&#x22; state of toggle buttons.',
      },
      'aria-disabled': {
        type: 'boolean | &#x22;true&#x22; | &#x22;false&#x22;',
        description: 'Indicates whether the element is disabled to users of assistive technology.',
      },
      'aria-expanded': {
        type: 'boolean | &#x22;true&#x22; | &#x22;false&#x22;',
        description: 'Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed.',
      },
      'aria-haspopup': {
        type: 'boolean | &#x22;true&#x22; | &#x22;false&#x22; | &#x22;dialog&#x22; | &#x22;grid&#x22; | &#x22;listbox&#x22; | &#x22;menu&#x22; | &#x22;tree&#x22;',
        description: 'Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element.',
      },
      'aria-controls': {
        type: 'string',
        description: 'Identifies the element (or elements) whose contents or presence are controlled by the current element.',
      },
      excludeFromTabOrder: {
        type: 'boolean',
        description: 'Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.',
      },
      preventFocusOnPress: {
        type: 'boolean',
        description: &#x22;Whether to prevent focus from moving to the button when pressing it. Caution, this can make the button inaccessible and should only be used when alternative keyboard interaction is provided, such as ComboBox's MenuTrigger or a NumberField's increment/decrement control.&#x22;,
      },
    }"
    />
  </Accordion>

  <Accordion title="Advanced">
    <TypeTable
      type="{
      autoFocus: {
        type: 'boolean',
        description: 'Whether the element should receive focus on render.',
      },
      dir: {
        type: 'string',
        description: 'Direction of text.',
      },
      hidden: {
        type: 'boolean',
        description: 'Whether the element is hidden.',
      },
      inert: {
        type: 'boolean',
        description: 'Whether the element is inert.',
      },
      lang: {
        type: 'string',
        description: 'Language code of the element.',
      },
      slot: {
        type: 'string | null',
        description: 'A slot name for the component. Slots allow the component to receive props from a parent component. An explicit null value indicates that the local props completely override all props received from a parent.',
      },
    }"
    />
  </Accordion>
</Accordions>

Default className: `react-aria-ToggleButton`

| Render Prop                                                                       | CSS Selector           |
| :-------------------------------------------------------------------------------- | :--------------------- |
| `isSelected` <br /> Whether the button is currently selected.                     | `[data-selected]`      |
| `state` <br /> State of the toggle button.                                        | —                      |
| `isHovered` <br /> Whether the button is currently hovered with a mouse.          | `[data-hovered]`       |
| `isPressed` <br /> Whether the button is currently in a pressed state.            | `[data-pressed]`       |
| `isFocused` <br /> Whether the button is focused, either via a mouse or keyboard. | `[data-focused]`       |
| `isFocusVisible` <br /> Whether the button is keyboard focused.                   | `[data-focus-visible]` |
| `isDisabled` <br /> Whether the button is disabled.                               | `[data-disabled]`      |


# ToggleButtonGroup (/docs/components/togglebuttongroup)





# ToggleButtonGroup [#togglebuttongroup]

A toggle button group represents a set of related buttons that can be toggled on or off, supporting both single and multiple selection.

## Preview [#preview]

<ComponentPreview>
  <div className="flex flex-col gap-6 w-full max-w-md">
    <div className="flex flex-col gap-2">
      <span className="text-sm font-medium text-muted-foreground">
        Standard Group
      </span>

      <ToggleButtonGroup defaultValue="['center']">
        <ToggleButton id="left">
          Left
        </ToggleButton>

        <ToggleButton id="center">
          Center
        </ToggleButton>

        <ToggleButton id="right">
          Right
        </ToggleButton>
      </ToggleButtonGroup>
    </div>

    <div className="flex flex-col gap-2">
      <span className="text-sm font-medium text-muted-foreground">
        Icon Toolbar (Multiple Selection)
      </span>

      <ToggleButtonGroup selectionMode="multiple" defaultValue="['bold', 'underline']">
        <ToggleButton id="bold" aria-label="Bold">
          <Bold className="w-4 h-4" />
        </ToggleButton>

        <ToggleButton id="italic" aria-label="Italic">
          <Italic className="w-4 h-4" />
        </ToggleButton>

        <ToggleButton id="underline" aria-label="Underline">
          <Underline className="w-4 h-4" />
        </ToggleButton>
      </ToggleButtonGroup>
    </div>

    <div className="flex flex-col gap-2">
      <span className="text-sm font-medium text-muted-foreground">
        Animated (Segmented Control)
      </span>

      <ToggleButtonGroup defaultValue="week">
        <ToggleButton id="day">
          Day
        </ToggleButton>

        <ToggleButton id="week">
          Week
        </ToggleButton>

        <ToggleButton id="month">
          Month
        </ToggleButton>

        <ToggleButton id="year">
          Year
        </ToggleButton>
      </ToggleButtonGroup>
    </div>
  </div>
</ComponentPreview>

## Import [#import]

```tsx
import { ToggleButtonGroup, ToggleButton } from '@moul-dev/ui';
```

## Examples [#examples]

### Classic adjacent group [#classic-adjacent-group]

By default, the buttons in a `ToggleButtonGroup` touch and share border radiuses, showing a unified toolbar appearance:

```tsx
<ToggleButtonGroup defaultValue={['left']}>
  <ToggleButton id="left">Left</ToggleButton>
  <ToggleButton id="center">Center</ToggleButton>
  <ToggleButton id="right">Right</ToggleButton>
</ToggleButtonGroup>
```

### Icon Toolbar [#icon-toolbar]

You can render icons inside the `<ToggleButton>` components. When rendering icon-only buttons, make sure to add an `aria-label` to each button for accessibility:

```tsx
import { ToggleButtonGroup, ToggleButton } from '@moul-dev/ui';
import { Bold, Italic, Underline } from 'lucide-react';

export default function Example() {
  return (
    <ToggleButtonGroup selectionMode="multiple" defaultValue={['bold', 'underline']}>
      <ToggleButton id="bold" aria-label="Bold">
        <Bold className="w-4 h-4" />
      </ToggleButton>
      <ToggleButton id="italic" aria-label="Italic">
        <Italic className="w-4 h-4" />
      </ToggleButton>
      <ToggleButton id="underline" aria-label="Underline">
        <Underline className="w-4 h-4" />
      </ToggleButton>
    </ToggleButtonGroup>
  );
}
```

### Animated Segmented Control [#animated-segmented-control]

Use the `animated` prop to style the group as a modern segmented control with a sliding selection indicator.

```tsx
<ToggleButtonGroup animated defaultValue="day">
  <ToggleButton id="day">Day</ToggleButton>
  <ToggleButton id="week">Week</ToggleButton>
  <ToggleButton id="month">Month</ToggleButton>
</ToggleButtonGroup>
```

### Vertical orientation [#vertical-orientation]

Use the `orientation` prop to align the group vertically:

<ComponentPreview>
  <div className="flex gap-8">
    <ToggleButtonGroup orientation="vertical" defaultValue="b">
      <ToggleButton id="a">
        Option A
      </ToggleButton>

      <ToggleButton id="b">
        Option B
      </ToggleButton>

      <ToggleButton id="c">
        Option C
      </ToggleButton>
    </ToggleButtonGroup>

    <ToggleButtonGroup orientation="vertical" defaultValue="b">
      <ToggleButton id="a">
        Option A
      </ToggleButton>

      <ToggleButton id="b">
        Option B
      </ToggleButton>

      <ToggleButton id="c">
        Option C
      </ToggleButton>
    </ToggleButtonGroup>
  </div>
</ComponentPreview>

## Props [#props]

### ToggleButtonGroup Props [#togglebuttongroup-props]

<TypeTable
  type="{
  'size': {
    type: &#x22;'sm' | 'md' | 'lg'&#x22;,
    default: &#x22;'md'&#x22;,
    description: &#x22;The size variant height applied to toggle buttons inside the group.&#x22;,
  },
  'animated': {
    type: &#x22;boolean&#x22;,
    default: &#x22;false&#x22;,
    description: &#x22;Enables smooth slide and size selection indicators overlay track animations.&#x22;,
  },
  'orientation': {
    type: &#x22;'horizontal' | 'vertical'&#x22;,
    default: &#x22;'horizontal'&#x22;,
    description: &#x22;The layout alignment axis orientation.&#x22;,
  },
  'selectionMode': {
    type: &#x22;'single' | 'multiple'&#x22;,
    default: &#x22;'single'&#x22;,
    description: &#x22;The selection behavior constraint.&#x22;,
  },
}"
/>

<Accordions>
  <Accordion title="Value">
    <TypeTable
      type="{
          'onSelectionChange': {
            type: &#x22;(keys: 'all' | Set<Key>) => void&#x22;,
            description: &#x22;Handler called when selection changes.&#x22;,
          },
        }"
    />
  </Accordion>

  <Accordion title="Styling">
    <TypeTable
      type="{
          'className': {
            type: &#x22;ClassNameOrFunction<ToggleButtonGroupRenderProps>&#x22;,
            default: &#x22;'react-aria-ToggleButtonGroup'&#x22;,
            description: &#x22;The CSS className.&#x22;,
          },
        }"
    />
  </Accordion>
</Accordions>

Default className: `react-aria-ToggleButtonGroup`

| Render Prop                                        | CSS Selector         |
| :------------------------------------------------- | :------------------- |
| `orientation` <br /> The orientation of the group. | `[data-orientation]` |
| `isDisabled` <br /> Whether the group is disabled. | `[data-disabled]`    |


# Tooltip (/docs/components/tooltip)





# Tooltip [#tooltip]

## Preview [#preview]

<ComponentPlayground component="Tooltip" />

The `Tooltip` component is built with React Aria and styled using StyleX.

## Import [#import]

```tsx
import { Tooltip } from '@moul-dev/ui';
```

## Usage [#usage]

Here is a basic example of how to use the `Tooltip` component:

```tsx
import { Tooltip } from '@moul-dev/ui';

export default function Example() {
  return (
    <Tooltip>
      {/* Component content */}
    </Tooltip>
  );
}
```

## Props [#props]

### Tooltip Props [#tooltip-props]

<TypeTable
  type="{
  'placement': {
    type: &#x22;string&#x22;,
    default: &#x22;'top'&#x22;,
    description: &#x22;The placement of the tooltip relative to its trigger.&#x22;,
  },
  'offset': {
    type: &#x22;number&#x22;,
    default: &#x22;8&#x22;,
    description: &#x22;The distance between the tooltip and the trigger button.&#x22;,
  },
  'crossOffset': {
    type: &#x22;number&#x22;,
    default: &#x22;0&#x22;,
    description: &#x22;The offset along the cross axis.&#x22;,
  },
  'isOpen': {
    type: &#x22;boolean&#x22;,
    description: &#x22;Whether the tooltip is open (controlled).&#x22;,
  },
  'defaultOpen': {
    type: &#x22;boolean&#x22;,
    description: &#x22;Whether the tooltip is initially open (uncontrolled).&#x22;,
  },
}"
/>

<Accordions>
  <Accordion title="Value">
    <TypeTable
      type="{
          'onOpenChange': {
            type: &#x22;(isOpen: boolean) => void&#x22;,
            description: &#x22;Handler called when open state changes.&#x22;,
          },
        }"
    />
  </Accordion>

  <Accordion title="Styling">
    <TypeTable
      type="{
          'className': {
            type: &#x22;ClassNameOrFunction<TooltipRenderProps>&#x22;,
            default: &#x22;'react-aria-Tooltip'&#x22;,
            description: &#x22;The CSS className.&#x22;,
          },
        }"
    />
  </Accordion>
</Accordions>

Default className: `react-aria-Tooltip`

| Render Prop                                            | CSS Selector       |
| :----------------------------------------------------- | :----------------- |
| `isOpen` <br /> Whether the tooltip is currently open. | `[data-open]`      |
| `placement` <br /> The placement of the tooltip.       | `[data-placement]` |


# Typography (/docs/components/typography)





# Typography [#typography]

## Preview [#preview]

<ComponentPlayground component="Typography" />

The `Typography` component is built with React Aria and styled using StyleX. It provides semantic subcomponents for cleaner, more readable markup.

## Semantic Components [#semantic-components]

Instead of specifying the `as` prop manually, you can use semantic subcomponents exported directly from `Typography`:

<ComponentPreview>
  <div className="flex flex-col gap-4 w-full">
    <TypographyHeading as="h1">
      Heading 1 (Typography.Heading as="h1")
    </TypographyHeading>

    <TypographyHeading as="h3">
      Heading 3 (Typography.Heading as="h3")
    </TypographyHeading>

    <TypographyParagraph>
      Paragraph (Typography.Paragraph) - Standard body text.
    </TypographyParagraph>

    <TypographySpan>
      Span (Typography.Span) - Inline text element.
    </TypographySpan>

    <TypographyLabel>
      Label (Typography.Label) - Form label element.
    </TypographyLabel>
  </div>
</ComponentPreview>

```tsx
import { Typography } from '@moul-dev/ui';

export default function Example() {
  return (
    <>
      <Typography.Heading as="h1">Heading 1</Typography.Heading>
      <Typography.Heading as="h3">Heading 3</Typography.Heading>
      <Typography.Paragraph>This is a paragraph.</Typography.Paragraph>
      <Typography.Span>This is a span.</Typography.Span>
      <Typography.Label>This is a label.</Typography.Label>
    </>
  );
}
```

## HTML Tags [#html-tags]

You can specify the HTML tag to render using the `as` prop on the base `Typography` component.

<ComponentPreview>
  <div className="flex flex-col gap-4 w-full">
    <Typography as="h1">
      Heading 1 (h1)
    </Typography>

    <Typography as="h2">
      Heading 2 (h2)
    </Typography>

    <Typography as="h3">
      Heading 3 (h3)
    </Typography>

    <Typography as="h4">
      Heading 4 (h4)
    </Typography>

    <Typography as="h5">
      Heading 5 (h5)
    </Typography>

    <Typography as="h6">
      Heading 6 (h6)
    </Typography>

    <Typography as="p">
      Paragraph (p) - Standard body text.
    </Typography>

    <Typography as="span">
      Span (span) - Inline text wrapper.
    </Typography>

    <Typography as="label">
      Label (label) - Form label style.
    </Typography>
  </div>
</ComponentPreview>

```tsx
<Typography as="h1">Heading 1 (h1)</Typography>
<Typography as="h2">Heading 2 (h2)</Typography>
<Typography as="h3">Heading 3 (h3)</Typography>
<Typography as="h4">Heading 4 (h4)</Typography>
<Typography as="h5">Heading 5 (h5)</Typography>
<Typography as="h6">Heading 6 (h6)</Typography>
<Typography as="p">Paragraph (p)</Typography>
<Typography as="span">Span (span)</Typography>
<Typography as="label">Label (label)</Typography>
```

## Import [#import]

```tsx
import { Typography } from '@moul-dev/ui';
```

## Usage [#usage]

Here is a basic example of how to use the `Typography` semantic subcomponents:

```tsx
import { Typography } from '@moul-dev/ui';

export default function Example() {
  return (
    <Typography.Paragraph>
      Quick brown fox jumps over the lazy dog.
    </Typography.Paragraph>
  );
}
```

## Props [#props]

### Typography Props [#typography-props]

<TypeTable
  type="{
  'as': {
    type: &#x22;'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'span' | 'label'&#x22;,
    default: &#x22;'span'&#x22;,
    description: &#x22;The HTML tag to render the typography element as.&#x22;,
  },
  'className': {
    type: &#x22;string&#x22;,
    description: &#x22;Additional CSS class names to apply to the element.&#x22;,
  },
  'style': {
    type: &#x22;StyleXStyles&#x22;,
    description: &#x22;StyleX style object to apply custom compile-time CSS.&#x22;,
  },
}"
/>


# Get Started (/docs)



Moul UI is a modular component library designed for product engineers who want a modern, consistent, and highly accessible baseline for React applications.

By merging the robust, accessible foundations of **React Aria** with the compile-time type safety and efficiency of **StyleX**, Moul UI delivers beautiful default styles with zero runtime styling overhead.

***

## Why Moul UI? [#why-moul-ui]

<Cards>
  <Card title="Accessible by Default" description="Full keyboard navigation, screen reader support, and robust interaction states powered by React Aria." />

  <Card title="Zero-Runtime Styling" description="Built on StyleX. Atomic CSS is fully compiled and extracted at build time, resulting in zero Javascript style overhead." />

  <Card title="Clean & Adaptable" description="A clean baseline of components designed to be easily modified and custom-themed to fit your branding." />
</Cards>

***

## Installation [#installation]

Follow these steps to integrate `@moul-dev/ui` into your React project:

<Steps>
  <Step>
    ### Install the Package [#install-the-package]

    Add the library and its peer dependencies to your workspace:

    <Tabs items="['Bun', 'npm', 'pnpm', 'yarn']">
      <Tab value="Bun">
        ```bash
        bun add @moul-dev/ui
        ```
      </Tab>

      <Tab value="npm">
        ```bash
        npm install @moul-dev/ui
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm add @moul-dev/ui
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn add @moul-dev/ui
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Import the CSS Stylesheet [#import-the-css-stylesheet]

    To load the compiled StyleX atomic styles, import the stylesheet at the root of your application (typically in `main.tsx`, `index.tsx`, or your global CSS file):

    ```ts
    import '@moul-dev/ui/style.css';
    ```
  </Step>

  <Step>
    ### Wrap your App with ThemeProvider (Optional) [#wrap-your-app-with-themeprovider-optional]

    Wrap your application tree (or specific sections) with the `ThemeProvider` to control the color scheme or apply token overrides:

    ```tsx
    import { ThemeProvider } from '@moul-dev/ui';

    function App({ children }) {
      return (
        <ThemeProvider colorScheme="light dark">
          {children}
        </ThemeProvider>
      );
    }
    ```
  </Step>

  <Step>
    ### Use the Components [#use-the-components]

    Now you can import and use any of the Moul UI components:

    ```tsx
    import { Button } from '@moul-dev/ui';

    function HomePage() {
      return (
        <div style={{ padding: '2rem', display: 'flex', gap: '1rem' }}>
          <Button variant="primary" onPress={() => console.log('Primary clicked!')}>
            Primary Button
          </Button>
          <Button variant="secondary" onPress={() => console.log('Secondary clicked!')}>
            Secondary Button
          </Button>
        </div>
      );
    }
    ```
  </Step>
</Steps>

***

## Next Steps [#next-steps]

Explore the components sidebars to see all the available interactive elements, variations, and configuration settings!


# LLMs & AI Agents (/docs/llms)





Moul UI provides dedicated machine-readable context files optimized for LLMs and AI coding assistants such as **Cursor**, **Windsurf**, **Claude Projects**, **GitHub Copilot**, **ChatGPT**, and **Antigravity**.

By providing your AI assistant with the curated context files below, the model will accurately generate accessible React Aria interactions, correctly import compound components, and adhere to zero-runtime StyleX design tokens without inventing hallucinated APIs.

***

## Machine-Readable Context Files [#machine-readable-context-files]

We host three standardized AI context files at the root of the documentation site:

<Cards>
  <Card title="llms.txt" href="/llms.txt" description="Concise documentation index, package quickstart, and component URLs following the llmstxt.org specification." />

  <Card title="llms-full.txt" href="/llms-full.txt" description="Complete documentation, API signatures, prop definitions, and code examples for all 38+ components in a single file." />

  <Card title="AGENTS.md" href="/AGENTS.md" description="System rules, code generation recipes, React Aria event conventions, and anti-patterns specifically formatted for coding agents." />
</Cards>

***

## Tool Integration Guides [#tool-integration-guides]

Choose your AI coding assistant below for quick setup instructions:

<Tabs items="['Cursor', 'Windsurf', 'Claude Projects', 'Copilot / VS Code', 'ChatGPT / Custom GPTs']">
  <Tab value="Cursor">
    ### Setting Up Cursor [#setting-up-cursor]

    Cursor supports Project Rules via `.cursor/rules` or `.cursorrules`.

    <Steps>
      <Step>
        #### Create a Rule File [#create-a-rule-file]

        Create `.cursor/rules/moul-ui.mdc` in your workspace:

        ```markdown title=".cursor/rules/moul-ui.mdc"
        ---
        description: Guidelines for building React components with @moul-dev/ui
        globs: "**/*.{ts,tsx}"
        alwaysApply: true
        ---

        When writing or editing React components:
        - Use @moul-dev/ui for all UI components, dialogs, forms, and charts.
        - Ensure `@moul-dev/ui/style.css` is imported at the application root.
        - Use `onPress` instead of `onClick` on `<Button>`, `<Link>`, and interactive triggers.
        - Use React Aria collection selection props (`selectedKey`, `onSelectionChange`).
        - For complete recipes and prop tables, refer to: https://moul.dev/AGENTS.md
        ```
      </Step>

      <Step>
        #### Add Documentation Docs URL [#add-documentation-docs-url]

        In Cursor Settings → **Features** → **Docs**, add:

        * **URL**: `https://moul.dev/llms.txt` or your deployed docs URL
        * **Prefix**: `@moul-ui`
      </Step>
    </Steps>
  </Tab>

  <Tab value="Windsurf">
    ### Setting Up Windsurf [#setting-up-windsurf]

    Add instructions to your `.windsurfrules` file:

    ```markdown title=".windsurfrules"
    # Moul UI Guidelines
    - Component Library: @moul-dev/ui
    - Global Styles: import '@moul-dev/ui/style.css'
    - Buttons & Triggers: Use `onPress={(e) => ...}` (React Aria) instead of `onClick`.
    - Modals & Overlays: Use `<ModalOverlay isOpen={...} onOpenChange={...}>` with `<Modal>`, `<ModalDialog>`, `<ModalHeader>`, `<ModalBody>`, `<ModalFooter>`.
    - Reference: Fetch https://moul.dev/AGENTS.md for complete component API specifications.
    ```
  </Tab>

  <Tab value="Claude Projects">
    ### Setting Up Claude Projects & Artifacts [#setting-up-claude-projects--artifacts]

    <Steps>
      <Step>
        #### Download Context File [#download-context-file]

        Download [`llms-full.txt`](/llms-full.txt) or [`AGENTS.md`](/AGENTS.md).
      </Step>

      <Step>
        #### Add to Project Knowledge [#add-to-project-knowledge]

        1. Open your project in [claude.ai](https://claude.ai).
        2. Navigate to **Project Knowledge**.
        3. Upload `llms-full.txt` or `AGENTS.md`.
      </Step>

      <Step>
        #### Set Custom Instructions [#set-custom-instructions]

        Add this snippet to Project Custom Instructions:

        ```text
        When writing frontend code, build UI interfaces using @moul-dev/ui according to the component recipes in AGENTS.md. Always use onPress for buttons and ensure accessible labels on icon triggers.
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab value="Copilot / VS Code">
    ### Setting Up GitHub Copilot [#setting-up-github-copilot]

    Create a workspace instructions file at `.github/copilot-instructions.md`:

    ```markdown title=".github/copilot-instructions.md"
    # Frontend Component Standards
    - Always use @moul-dev/ui components for buttons, forms, tables, modals, and charts.
    - Global CSS: Ensure `@moul-dev/ui/style.css` is imported in `main.tsx`.
    - Event Handlers: Use `onPress` instead of `onClick` on Buttons.
    - Dialogs: Use compound subcomponents (`ModalOverlay`, `ModalDialog`, `ModalHeader`, `ModalBody`, `ModalFooter`).
    - Details: Refer to https://moul.dev/AGENTS.md.
    ```
  </Tab>

  <Tab value="ChatGPT / Custom GPTs">
    ### Setting Up ChatGPT & Custom GPTs [#setting-up-chatgpt--custom-gpts]

    In your Custom GPT configuration:

    1. Upload [`AGENTS.md`](/AGENTS.md) and [`llms-full.txt`](/llms-full.txt) under **Knowledge Files**.
    2. Add the following to **Instructions**:

    ```text
    You are an expert React engineer specialized in building accessible, high-performance web applications using @moul-dev/ui and StyleX. Follow the conventions in AGENTS.md for all component imports and props.
    ```
  </Tab>
</Tabs>

***

## Golden Rules for AI Generation [#golden-rules-for-ai-generation]

When prompting an AI to generate interfaces with Moul UI, instruct the model to follow these core rules:

<Accordions>
  <Accordion title="1. Event Handlers: onPress vs onClick">
    Moul UI buttons and action triggers are built on React Aria and use `onPress`:

    ```tsx
    // ✅ Correct
    <Button variant="primary" onPress={() => handleSave()}>Save Changes</Button>

    // ❌ Incorrect
    <Button variant="primary" onClick={() => handleSave()}>Save Changes</Button>
    ```
  </Accordion>

  <Accordion title="2. Compound Component Architecture">
    Complex components like `Modal`, `AlertDialog`, `Card`, `Tabs`, `Table`, `Select`, and `Sidebar` use declarative compound subcomponents:

    ```tsx
    // ✅ Correct Modal structure
    <ModalOverlay isOpen={isOpen} onOpenChange={setIsOpen}>
      <Modal size="md">
        <ModalDialog>
          <ModalHeader><h3>Title</h3></ModalHeader>
          <ModalBody><p>Body text</p></ModalBody>
          <ModalFooter><Button onPress={() => setIsOpen(false)}>Done</Button></ModalFooter>
        </ModalDialog>
      </Modal>
    </ModalOverlay>
    ```
  </Accordion>

  <Accordion title="3. Accessible Labelling">
    All icon-only buttons **must** include an `aria-label`:

    ```tsx
    // ✅ Accessible
    <Button variant="ghost" aria-label="Delete project" onPress={handleDelete}>
      <TrashIcon />
    </Button>
    ```
  </Accordion>

  <Accordion title="4. Design Tokens & Theming">
    Custom branding is configured with CSS custom properties or `<ThemeProvider>`:

    ```css
    :root {
      --brand-hue: 250;               /* Primary hue */
      --brand-chroma-multiplier: 1.0; /* Saturation */
      --brand-radius-factor: 1.0;     /* Corner roundness */
      --brand-density-factor: 1.0;    /* Spacing & density */
    }
    ```
  </Accordion>
</Accordions>

***

## Example Prompts for AI Assistants [#example-prompts-for-ai-assistants]

Here are prompt templates you can copy and paste into your AI assistant:

<Steps>
  <Step>
    #### Dashboard & Analytics View Prompt [#dashboard--analytics-view-prompt]

    ```text
    Create a responsive analytics dashboard using @moul-dev/ui.
    - Include Stat cards showing Revenue, Active Users, and Conversion Rate.
    - Add an AreaChart for monthly financial trends and a BarChart for traffic sources.
    - Include a recent transactions Table with selection and status Badges.
    - Follow @moul-dev/ui component imports and onPress handlers.
    ```
  </Step>

  <Step>
    #### Settings & Modal Form Prompt [#settings--modal-form-prompt]

    ```text
    Build a user settings page with @moul-dev/ui.
    - Include TextFields for Name and Email, a Select for Role, and a Switch for Two-Factor Authentication.
    - Add an "Invite Colleague" Button that opens a Modal with an email form and confirmation actions.
    - Dispatch a success notification using toastQueue.add() when changes are saved.
    ```
  </Step>
</Steps>