# Fluid UI Full Documentation

> Fluid UI is an open-source React component library providing styled UI primitives, customizable themes, and a fast CSS compilation workflow.
> For version release notes and breaking changes, see [changelog.md](https://fluid.infinityfx.dev/docs/changelog.md).

## Getting Started

### Installation

```bash
npm install @infinityfx/fluid
```

### Adding the Fluid Provider

Wrap your application root with `<FluidProvider>` so all components are styled correctly and theming functions properly. `<FluidProvider>` is a polymorphic component that renders as a wrapper element supplying its children with selected theme data. By default it renders as an HTML `<body>` element (used in place of your normal `<body>` tag). If your framework does not allow manually rendering a `<body>` tag, use the `as` prop to render it as a different element, such as a `<div>`:

```tsx
// app/layout.tsx (Next.js App Router)
import { FluidProvider } from '@infinityfx/fluid';

export default function RootLayout({ children }: { children: React.ReactNode }) {
    return (
        <html>
            <FluidProvider>
                {children}
            </FluidProvider>
        </html>
    );
}
```

```tsx
// App.tsx (Using 'as' prop for custom wrapper)
import { FluidProvider } from '@infinityfx/fluid';

export default function App() {
    return (
        <FluidProvider as="div">
            Hello world!
        </FluidProvider>
    );
}
```

### Compilation

Before running your application, compile component styles to CSS:

```bash
# Production compilation (tree-shakes unused component styles)
npx fluid compile

# Development compilation (includes all styles to prevent missing classes during dev)
npx fluid compile -d
```

Prepend compilation to your `package.json` scripts:

```json
{
  "scripts": {
    "dev": "npx fluid compile -d && next dev",
    "build": "npx fluid compile && next build"
  }
}
```

## Configuration

Create a `fluid.config.js` or `fluid.config.mjs` file in your project root:

```js
/** @type {import('@infinityfx/fluid').FluidConfig} */
module.exports = {
    // Configure scanned paths (default patterns)
    paths: [
        './src/**/*.{jsx,tsx}',
        './app/**/*.{jsx,tsx}',
        './pages/**/*.{jsx,tsx}',
        './components/**/*.{jsx,tsx}'
    ],
    // Recommended for Next.js to prevent stale cached styles in node_modules
    cssOutput: 'manual'
};
```

### Custom Icons

Override internal component icons by assigning React components (e.g. from `react-icons/lu`):

```js
const { LuPlus, LuCheck, LuX, LuChevronDown, LuSearch, LuMoon, LuSun } = require('react-icons/lu');

module.exports = {
    icons: {
        add: LuPlus,
        check: LuCheck,
        close: LuX,
        down: LuChevronDown,
        search: LuSearch,
        dark: LuMoon,
        light: LuSun
    }
};
```

## Theming & Styling

### CSS Variable Naming & Token Schema

Fluid UI uses strict CSS variable naming schemas. When writing styles or overriding component colors and spacing, strictly adhere to the following rules:

- **Color Variables (`--f-clr-[palette]-[step]`)**: Color variables **MUST** include a numeric step suffix (`-100` to `-900`). Index `0` of a palette array maps to `-100` (`-200` is index 1, up to `-900`). Never omit the step (e.g., use `--f-clr-primary-100`, never `--f-clr-primary`).
- **Spacing & Size Variables (`--f-spacing-[size]`)**: Size suffixes span from `-xxs` to `-xxl` (`-xxs`, `-xsm`, `-sml`, `-med`, `-lrg`, `-xlg`, `-xxl`). Do NOT use standard Tailwind/web suffixes (`-sm`, `-md`, `-lg`, `-xl`).
- **Component Size Availability**: Note that individual components may support only a subset of the full `xxs`–`xxl` size range (e.g., `xsm` to `lrg`). Always verify supported sizes via component prop types.

| Pattern | Invalid | Valid Fluid Variable |
| :--- | :--- | :--- |
| **Color** (Step required) | `var(--f-clr-primary)` | `var(--f-clr-primary-100)` |
| **Spacing / Size** (Fluid suffixes) | `var(--f-spacing-lg)` | `var(--f-spacing-lrg)` |

### Color Palettes & mixColors()

Customize or add color palettes in `fluid.config.js`. Use `mixColors()` from `@infinityfx/fluid/utils` to auto-generate color scales:

```js
const { mixColors } = require('@infinityfx/fluid/utils');

module.exports = {
    theme: {
        palettes: {
            light: {
                primary: mixColors('#22e39f', '#ffffff', 6)
            },
            myCustomPalette: {
                primary: ['#22e39f', '#45e6ad', '#60f0bd', '#8cf5d0', '#baf7e2', '#dcfcf1'],
                myCustomColor: mixColors('#22e39f', '#ffffff', 6)
            }
        }
    }
};
```

### Switching Themes with useFluid()

Use the `useFluid` hook to toggle themes or read the active color scheme:

```tsx
import { useFluid } from '@infinityfx/fluid/hooks';

export function ThemeToggle() {
    const { colorScheme, appliedColorScheme, setColorScheme } = useFluid();
    // colorScheme can be 'light', 'dark', 'myCustomPalette', or 'system'
    return (
        <button onClick={() => setColorScheme(colorScheme === 'dark' ? 'light' : 'dark')}>
            Active: {appliedColorScheme}
        </button>
    );
}
```

### Server-Side Rendering (SSR) Cookie Setup

To prevent theme flashes on page load in SSR frameworks (like Next.js), read the `COLOR_SCHEME_COOKIE` on the server and pass it to `initialColorScheme`:

```tsx
// app/layout.tsx
import { COLOR_SCHEME_COOKIE } from '@infinityfx/fluid/utils';
import { FluidProvider } from '@infinityfx/fluid';
import { cookies } from 'next/headers';

export default async function RootLayout({ children }: { children: React.ReactNode }) {
    const cookieStore = await cookies();
    const colorScheme = cookieStore.get(COLOR_SCHEME_COOKIE)?.value;

    return (
        <html>
            <FluidProvider initialColorScheme={colorScheme}>
                {children}
            </FluidProvider>
        </html>
    );
}
```

### Per-Instance Styling with the `cc` Prop

All Fluid UI components accept a `cc` (custom classes) prop to target specific internal component sub-elements or variant states:

```tsx
<Select
    options={[{ label: 'Option 1', value: 1 }]}
    cc={{
        v__default: 'custom-select-variant',
        placeholder: 'custom-placeholder-style'
    }}
/>
```

## Component Reference

### Accordion

A vertical list of collapsible sections that can be opened and closed.

#### Importing

```tsx
import { AccordionRoot, AccordionItem } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<AccordionRoot>
    <AccordionItem label="Why?">
        Just because.
    </AccordionItem>
    <AccordionItem label="How?">
        It doesn't matter.
    </AccordionItem>
    <AccordionItem label="When?">
        Always.
    </AccordionItem>
</AccordionRoot>
```

##### Disabled item

```tsx
<AccordionRoot>
    <AccordionItem label="Why?" defaultOpen>
        Just because.
    </AccordionItem>
    <AccordionItem label="How?" disabled>
        It doesn't matter.
    </AccordionItem>
</AccordionRoot>
```

#### API Reference

##### AccordionRoot Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `variant` | 'default' \| 'neutral' \| 'minimal' | `default` | - |
| `multiple` | `boolean` | `false` | Allow multiple items to be open at the same time. |

##### AccordionItem Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `label` | `React.ReactNode` | - | The label shown in the accordion item header. |
| `defaultOpen` | `boolean` | `false` | - |
| `disabled` | `boolean` | `false` | - |

---

### Action Menu

Displays a menu with actions or options.

#### Importing

```tsx
import { ActionMenuGroup, ActionMenuHeading, ActionMenuItem, ActionMenuMenu, ActionMenuRoot, ActionMenuTrigger } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<ActionMenuRoot
    variant="default"
    position="auto"
    stretch={false}>
    <ActionMenuTrigger>
        <Button>Menu</Button>
    </ActionMenuTrigger>

    <ActionMenuMenu>
        <ActionMenuHeading>My account</ActionMenuHeading>
        <ActionMenuItem>
            <LuArrowUpRight />
            View
        </ActionMenuItem>
        <ActionMenuGroup label={<>
            <LuSettings />
            Settings
        </>}>
            <ActionMenuItem>
                <LuGlobe />
                General
            </ActionMenuItem>
            <ActionMenuItem>
                <LuShield />
                Security
            </ActionMenuItem>
        </ActionMenuGroup>
        <Divider size="inherit" />
        <ActionMenuItem color="red">
            <LuTrash />
            Delete
        </ActionMenuItem>
    </ActionMenuMenu>
</ActionMenuRoot>
```

#### API Reference

##### ActionMenuRoot Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `round` | `boolean` | `false` | - |
| `stretch` | `boolean` | `false` | - |
| `variant` | 'default' \| 'inverted' | `default` | - |
| `position` | 'auto' \| 'center' | `auto` | - |
| `autoFocus` | `boolean` | `false` | - |

##### ActionMenuTrigger Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `longpress` | `boolean` | `false` | - |
| `disabled` | `boolean` | `false` | - |

##### ActionMenuGroup Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `label` | `React.ReactNode` | - | - |

##### ActionMenuItem Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `keepOpen` | `boolean` | `false` | - |

---

### Annotation

Displays a label or error message for an input field.

#### Importing

```tsx
import { Annotation } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Annotation>
    <Field />
</Annotation>
```

#### API Reference

##### Annotation Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `label` | `string` | - | The label text shown above the input field. |
| `error` | `string` | - | The error message shown below the input field. |

---

### Autocomplete

A text input which shows autocomplete suggestions.

#### Importing

```tsx
import { Autocomplete } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Autocomplete
    icon={<LuSearch />}
    completions={[
        'English',
        'Dutch',
        'Spanish'
    ]} />
```

#### API Reference

##### Autocomplete Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `completions` | `string[] | { label: string; value: string; }[]` | - | The list of autocomplete suggestions. |
| `emptyMessage` | `string` | `"No suggestions"` | Text shown when there are no completions to display. |
| `contentSize` | 'xsm' \| 'sml' \| 'med' \| 'lrg' | - | Size of the dropdown content. |
| `virtualItemHeight` | `number` | - | When set to a number greater than 0, enables virtual scrolling for better performance with large suggestion lists. |
| `value` | `string` | - | Controlled text value. |
| `defaultValue` | `string` | - | Default text value. |
| `size` | 'xsm' \| 'sml' \| 'med' \| 'lrg' | `med` | - |
| `variant` | 'default' \| 'minimal' | `default` | - |
| `round` | `boolean` | `false` | - |
| `icon` | `React.ReactNode` | - | Icon element displayed on the left side of the field. |
| `error` | `any` | - | Marks the field as invalid when truthy. |
| `disabled` | `boolean` | `false` | - |

---

### Badge

A badge used for displaying attributes or small information snippets.

#### Importing

```tsx
import { Badge } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Badge>
    Badge
</Badge>
```

#### API Reference

##### Badge Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `round` | `boolean` | `false` | - |
| `variant` | 'default' \| 'inverted' \| 'neutral' | `default` | - |
| `size` | 'xsm' \| 'sml' \| 'med' \| 'lrg' | `sml` | - |
| `color` | `string` | - | Custom background or text color override. |
| `onClose` | `() => void` | - | If provided, renders a close/remove button on the badge and calls this handler when clicked. |

---

### Button

A button.

#### Importing

```tsx
import { Button } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Button>
    Button
</Button>
```

##### With icon

```tsx
<Button>
    Button
    <LuArrowUpRight />
</Button>
```

##### As a link

```tsx
<Button as="a" href="#" variant="minimal">
    Button
    <LuArrowUpRight />
</Button>
```

#### API Reference

##### Button Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `round` | `boolean` | `false` | - |
| `compact` | `boolean` | `false` | Reduces block and inline padding for a smaller button footprint. |
| `size` | 'xsm' \| 'sml' \| 'med' \| 'lrg' | `med` | - |
| `variant` | 'default' \| 'neutral' \| 'inverted' \| 'muted' \| 'minimal' | `default` | - |
| `color` | `string` | - | Custom background color override. |
| `loading` | `boolean` | `false` | Shows a loading spinner instead of the button contents. |
| `disabled` | `boolean` | `false` | - |
| `hasIcon` | 'auto' \| 'start' \| 'end' \| 'only' | `auto` | Manually indicate whether this button has an icon to adjust it's padding. Only needed when automatic icons detection isn't possible. |

---

### Calendar

An input used for selecting a date.

#### Importing

```tsx
import { Calendar } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Calendar />
```

##### Disabled dates

```tsx
<Calendar
    disabled={[
        new Date('${date}')
    ]} />
```

##### Allowed range

```tsx
<Calendar
    maxDate={new Date()} />
```

#### API Reference

##### Calendar Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `locale` | `Intl.LocalesArgument` | - | Locale used for date formatting. |
| `size` | 'xsm' \| 'sml' \| 'med' \| 'lrg' | `med` | - |
| `round` | `boolean` | `false` | - |
| `value` | `Date | null` | - | Controlled selected date. |
| `defaultValue` | `Date` | - | Default selected date for uncontrolled usage. |
| `onChange` | `(value: Date) => void` | - | - |
| `disabled` | `boolean | Date[]` | `false` | Disables the calendar entirely when true, or disables specific dates when an array of dates is provided. |
| `minDate` | `Date` | - | Minimum selectable date. |
| `maxDate` | `Date` | - | Maximum selectable date. |

---

### Card

A versatile composable container component.

#### Importing

```tsx
import { Card, CardContent, CardHeader, CardBackdrop } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Group direction="vertical">
    <Card>
        <CardHeader pad="bottom">
            <h3>Card title</h3>

            <Button compact variant="muted">
                <LuX />
            </Button>
        </CardHeader>
        <CardContent>
            <Annotation label="First task">
                <ProgressBar value={.5} />
            </Annotation>
            <Annotation label="Second task">
                <ProgressBar value={.25} />
            </Annotation>
        </CardContent>
    </Card>
    <Card color="back">
        <CardContent align="horizontal" stretch>
            <Button compact variant="muted">
                Cancel
            </Button>
            <Button compact>
                Confirm
            </Button>
        </CardContent>
    </Card>
</Group>
```

##### Card title

```tsx
<Card pad="xsm" elevated>
    <CardContent gap='xsm'>
        <Card
            radius="sml"
            borderless
            style={{
                width: 300,
                height: 200,
                filter: 'blur(0px)' // fix nested backdrop-filter bug
            }}>
            <CardBackdrop fade="bottom">
                <img src="/images/image.png" width="100%" />
            </CardBackdrop>

            <CardContent style={{ height: '100%', justifyContent: 'end' }}>
                <h3 style={{ color: 'white' }}>Movie title</h3>
            </CardContent>
        </Card>

        <CardContent pad="xsm" gap='xsm'>
            <CardContent align="horizontal" gap="xsm">
                <Badge color="var(--f-clr-surface-200)">Action</Badge>
                <Badge color="var(--f-clr-surface-200)">Adventure</Badge>
            </CardContent>

            <CardHeader>
                <h3>Card title</h3>

                <Button compact variant="muted">
                    <LuArrowUpRight />
                </Button>
            </CardHeader>
        </CardContent>
    </CardContent>
</Card>
```

##### Card title

```tsx
<Interactable as={Card}>
    <CardContent align="horizontal" gap="none">
        <Swatch color="red" />
        <Divider vertical />
        <Swatch color="green" />
        <Divider vertical />
        <Swatch color="blue" />
    </CardContent>
</Interactable>
```

#### API Reference

##### Card Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `color` | 'front' \| 'back' \| 'top' | `front` | - |
| `elevated` | `boolean` | `false` | Shows a backdrop shadow. |
| `borderless` | `boolean` | `false` | - |
| `radius` | 'xsm' \| 'sml' \| 'med' \| 'lrg' | `med` | - |
| `pad` | 'none' \| 'xxs' \| 'xsm' \| 'sml' \| 'med' \| 'lrg' \| 'xlg' | `med` | - |

##### CardContent Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `align` | 'vertical' \| 'horizontal' \| 'center' | `vertical` | - |
| `stretch` | `boolean` | `false` | Let every child element fill all available space. |
| `pad` | 'none' \| 'xxs' \| 'xsm' \| 'sml' \| 'med' \| 'lrg' \| 'xlg' | `none` | - |
| `gap` | 'none' \| 'xsm' \| 'sml' \| 'med' \| 'lrg' | `sml` | - |

##### CardHeader Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `pad` | 'top' \| 'bottom' | - | When set adds spacing below or above the header. |
| `center` | `boolean` | `false` | Align content vertically centered, instead of to text baseline. |

##### CardBackdrop Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `fade` | 'top' \| 'bottom' | - | When set will fade out the backdrop to allow for contrast with overlayed content. |

---

### Checkbox

An input that switches between a checked and unchecked state.

#### Importing

```tsx
import { Checkbox } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Checkbox />
```

#### API Reference

##### Checkbox Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `size` | 'xsm' \| 'sml' \| 'med' \| 'lrg' | `med` | - |
| `color` | `string` | - | Custom accent color for the checkbox when checked. |
| `error` | `any` | - | Marks the checkbox as invalid when truthy. |
| `intermediate` | `boolean` | - | Displays an intermediate (indeterminate) state instead of the checked state. |
| `disabled` | `boolean` | `false` | - |

---

### Chip

An input that switches between a selected and unselected state.

#### Importing

```tsx
import { Chip } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Chip>
    Chip
</Chip>
```

#### API Reference

##### Chip Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `size` | 'xsm' \| 'sml' \| 'med' \| 'lrg' | `med` | - |
| `type` | 'checkbox' \| 'radio' | `checkbox` | Whether the chip behaves as a checkbox or a radio input. |
| `round` | `boolean` | `false` | - |
| `disabled` | `boolean` | `false` | - |

---

### Circular Progress

A circular indicator displaying the progress of something.

#### Importing

```tsx
import { CircularProgress } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<CircularProgress>
    Label
</CircularProgress>
```

#### API Reference

##### CircularProgress Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `size` | 'xsm' \| 'sml' \| 'med' \| 'lrg' | `med` | - |
| `color` | `string` | - | Custom color for the progress arc. |
| `value` | `number` | `0` | Progress value between 0 and 1. |
| `slice` | `number` | `0` | Fraction of the circle to cut off at the bottom (0 to 1). |
| `gap` | `number` | `0` | Gap between the progress arc and the track at the endpoints. |
| `fixedStrokeWidth` | `boolean` | `true` | When true, the stroke width remains constant regardless of the component size. |

---

### Code

Displays formatted code.

#### Importing

```tsx
import { Code } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Code>
    {`const text = 'hello world!';

    console.log(text);`}
</Code>
```

##### Syntax highlighting

```tsx
<Code
    title="hello-world.js"
    dangerouslyInject
    className={styles.code}>
    {Prism.highlight(`const text = 'hello world!';

    console.log(text);`, Prism.languages.javascript, 'javascript')}
</Code>
```

#### API Reference

##### Code Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `title` | `string` | - | A title header displayed above the code block. |
| `lineNumbers` | `boolean` | `true` | Displays line numbers on the left of the code block. |
| `dangerouslyInject` | `boolean` | `false` | Allows rendering pre-tokenized HTML string directly. Note: Use caution to avoid XSS. |

---

### Collapsible

An animated container which can hide its contents.

#### Importing

```tsx
import { Collapsible } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Collapsible>
    <img width={200} height={200} src="/images/image.png" />
</Collapsible>
```

#### API Reference

##### Collapsible Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `shown` | `boolean` | - | Whether the collapsible content is expanded and visible. |

---

### Color Field

An input field which displays a color picker.

#### Importing

```tsx
import { ColorField } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<ColorField />
```

##### With annotation

```tsx
<Annotation 
    label="Theme color">
    <ColorField />
</Annotation>
```

#### API Reference

##### ColorField Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `value` | `string` | - | Controlled hex color value. |
| `defaultValue` | `string` | - | Default hex color value for uncontrolled usage. |
| `onChange` | `(value: string) => void` | - | - |
| `size` | 'xsm' \| 'sml' \| 'med' \| 'lrg' | `med` | - |
| `variant` | 'default' \| 'minimal' | `default` | - |
| `round` | `boolean` | `false` | - |
| `icon` | `React.ReactNode` | - | Icon element displayed on the left side of the field. |
| `error` | `any` | - | Marks the field as invalid when truthy. |
| `disabled` | `boolean` | `false` | - |

---

### Color Picker

An input used for picking a color.

#### Importing

```tsx
import { ColorPicker } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<ColorPicker />
```

#### API Reference

##### ColorPicker Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `format` | 'hex' \| 'rgb' | - | Output format for color values. |
| `value` | `string | [number, number, number]` | - | Controlled color value. A hex string when format is hex, or an RGB array when format is rgb. |
| `defaultValue` | `string | [number, number, number]` | - | Default color value for uncontrolled usage. |
| `onChange` | `(value: string | [number, number, number]) => void` | - | - |
| `disabled` | `boolean` | `false` | - |

---

### Combobox

Displays a list of selectable options that can be searched through.

#### Importing

```tsx
import { ComboboxContent, ComboboxOption, ComboboxRoot, ComboboxTrigger } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<ComboboxRoot>
    <ComboboxTrigger>
        <Button>
            Select fruit
        </Button>
    </ComboboxTrigger>

    <ComboboxContent searchable>
        <ComboboxOption value="apples">
            <LuApple />
            Apples
        </ComboboxOption>
        <ComboboxOption value="bananas">
            <LuBanana />
            Bananas
        </ComboboxOption>
        <ComboboxOption value="cherries">
            <LuCherry />
            Cherries
        </ComboboxOption>
    </ComboboxContent>
</ComboboxRoot>
```

##### Groups

```tsx
<ComboboxRoot>
    <ComboboxTrigger>
        <Button>
            Select item
        </Button>
    </ComboboxTrigger>
        
    <ComboboxContent>
        <Tooltip content="A description of item 1">
            <ComboboxOption value="item 1">
                Item 1
            </ComboboxOption>
        </Tooltip>
        <Divider
            size="inherit"
            label="Group 2"
            labelPosition="start"
            style={{ paddingLeft: '.5em' }} />
        <ComboboxOption value="item 2">
            Item 2
        </ComboboxOption>
        <ComboboxOption value="item 3">
            Item 3
        </ComboboxOption>
    </ComboboxContent>
</ComboboxRoot>
```

#### API Reference

##### ComboboxRoot Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `round` | `boolean` | `false` | - |
| `stretch` | `boolean` | `false` | - |
| `variant` | 'default' \| 'inverted' | `default` | - |
| `position` | 'auto' \| 'center' | `auto` | - |
| `autoFocus` | `boolean` | `true` | Focus the first item or search field when opening the menu. |
| `mobileContainer` | 'popover' \| 'modal' | `popover` | How to display the dropdown content on mobile devices. |

##### ComboboxTrigger Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `longpress` | `boolean` | `false` | Requires a long press to open the combobox dropdown. |
| `disabled` | `boolean` | `false` | - |

##### ComboboxContent Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `size` | 'xsm' \| 'sml' \| 'med' \| 'lrg' | `med` | - |
| `searchable` | `boolean` | `false` | Enables a search field at the top of the dropdown. |
| `placeholder` | `string` | `"Search.."` | Placeholder text shown inside the search field. |
| `emptyMessage` | `string` | `"Nothing found"` | Text shown when no options match the search. |
| `virtualItemHeight` | `number` | - | When set to a number greater than 0, enables virtual scrolling for better performance with large option lists. |

##### ComboboxOption Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `value` | `T extends string | number | string[]` | - | The unique value associated with this option. |
| `disabled` | `boolean` | `false` | - |
| `onSelect` | `(value: T) => void` | - | - |

---

### Cull

Hides an element from the page for selected screen sizes.

#### Importing

```tsx
import { Cull } from '@infinityfx/fluid';
```

#### API Reference

##### Cull Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `include` | `('mob' | 'tab' | 'lap' | 'dsk')[]` | - | The screen breakpoints at which the wrapped element should be hidden/culled. |

---

### Date Field

An input used for entering dates.

#### Importing

```tsx
import { DateField } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<DateField />
```

##### With annotation

```tsx
<Annotation
    label="Arrival"
    error="Date is not available">
    <DateField error />
</Annotation>
```

#### API Reference

##### DateField Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `value` | 'Date' \| 'null' | - | Controlled selected date. |
| `defaultValue` | `Date` | - | Default selected date for uncontrolled usage. |
| `onChange` | `(value: Date | null) => void` | - | - |
| `clearable` | `boolean` | `false` | Shows a button to clear the selected date. |
| `locale` | `string` | - | A language and/or region identifier, determining the displayed language. |
| `size` | 'xsm' \| 'sml' \| 'med' \| 'lrg' | `med` | - |
| `variant` | 'default' \| 'minimal' | `default` | - |
| `round` | `boolean` | `false` | - |
| `icon` | `React.ReactNode` | - | Icon element displayed on the left side of the field. |
| `error` | `any` | - | Marks the field as invalid when truthy. |
| `disabled` | 'boolean' \| 'Date[]' | `false` | Disables the input entirely when true, or disables specific dates in the picker when an array of dates is provided. |

---

### Dial

An infinite circular number input.

#### Importing

```tsx
import { Dial } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Dial
    min={0}
    max={10}
    rowHeight={1.5}
    style={{ fontSize: '3rem', paddingInline: '.5em' }} />
```

#### API Reference

##### Dial Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `value` | `number` | - | - |
| `defaultValue` | `number` | - | Default value for uncontrolled usage. |
| `onChange` | `(value: number) => void` | - | - |
| `rows` | `number` | `4` | The number of options in view, which subsequently determines the height of the dial. |
| `rowHeight` | `number` | `1.2` | The height of an option row relative to the font size. Will also determine spacing between options. |
| `disabled` | `boolean` | `false` | - |

---

### Divider

A divider.

#### Importing

```tsx
import { Divider } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Divider
    style={{ width: '12rem', height: '12rem' }} />
```

#### API Reference

##### Divider Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `vertical` | `boolean` | `false` | Renders the divider vertically. |
| `label` | `string` | - | Optional text label displayed within the divider line. |
| `labelPosition` | 'start' \| 'center' \| 'end' | `center` | Position of the label along the divider line. |
| `size` | 'xsm' \| 'sml' \| 'med' \| 'lrg' \| 'inherit' | `med` | Padding spacing around the divider. |

---

### Drawer

Displays a container with content overlayed onto the side of the page.

#### Importing

```tsx
import { Drawer } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Drawer
    show={open} 
    onClose={() => setOpen(false)}>
    Drawer content.
</Drawer>

<Button onClick={() => setOpen(!open)}>
    Toggle drawer
</Button>
```

#### API Reference

##### Drawer Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `show` | `boolean` | - | Controlled visibility state of the drawer. |
| `onClose` | `() => void` | - | Callback function triggered when the drawer is closed (e.g. clicking the close button, overlay, or swiping). |
| `position` | 'left' \| 'right' | `right` | Which side of the screen the drawer slides out from. |
| `title` | `React.ReactNode` | - | Title text or element displayed in the header. |

---

### Drop Zone

An input that allows for drag and dropping files.

#### Importing

```tsx
import { DropZone } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<DropZone />
```

##### Accepted types

```tsx
<Annotation label="Upload avatar">
    <DropZone
        required
        icon={<LuImage />}
        accept="image/jpeg, image/jpg, image/png"
        text="Drop an image or click to browse"
        annotation="JPEG, JPG or PNG"
        style={{
            minWidth: 200,
            height: 200
        }} />
</Annotation>
```

#### API Reference

##### DropZone Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `loading` | `boolean` | `false` | Shows a loading spinner while true. |
| `error` | `any` | - | Marks the drop zone as invalid when truthy. |
| `text` | `string` | `"Drop files or click to browse"` | Instruction text shown in the empty state. |
| `annotation` | `string` | - | Additional annotation text shown below the main text. |
| `icon` | `React.ReactNode` | - | Custom icon shown in the empty state. |
| `previewImages` | `boolean` | `false` | Shows a preview when an image file is selected. |
| `fallbackPreviewImage` | `string` | - | Fallback image URL to show when no file is selected but previewImages is enabled. |
| `inputRef` | `React.Ref<HTMLInputElement>` | - | Ref forwarded to the underlying file input element. |
| `onChange` | `React.ChangeEventHandler<HTMLInputElement>` | - | - |
| `disabled` | `boolean` | `false` | - |

---

### Empty

Displays an empty state.

#### Importing

```tsx
import { Empty } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Empty>
    <Button compact>Create new</Button>
    <Button compact variant="neutral">Import</Button>
</Empty>
```

#### API Reference

##### Empty Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `title` | `string` | `required` | - |
| `message` | `string` | - | Additional descriptive text shown below the title. |
| `icon` | `React.ReactNode` | - | Custom icon shown above the title. |

---

### Field

An input used for entering text based information.

#### Importing

```tsx
import { Field } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Field />
```

##### With annotation

```tsx
<Annotation 
    label="Username"
    error="Username is already in use">
    <Field required />
</Annotation>
```

##### Shape filter

```tsx
<Field
    placeholder="+31 612345678"
    shape="+31 6%d%d%d%d%d%d%d%d%d" />
```

#### API Reference

##### Field Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `size` | 'xsm' \| 'sml' \| 'med' \| 'lrg' | `med` | - |
| `variant` | 'default' \| 'minimal' | `default` | - |
| `round` | `boolean` | `false` | - |
| `icon` | `React.ReactNode` | - | Icon element displayed on the left side of the field. |
| `error` | `any` | - | Marks the field as invalid when truthy. |
| `left` | `React.ReactNode` | - | Static element shown before the input text. |
| `right` | `React.ReactNode` | - | Static element shown after the input text. |
| `shape` | `string` | - | Format pattern representing character constraints (e.g., %d for digits). |
| `disabled` | `boolean` | `false` | - |
| `onEnter` | `() => void` | - | Callback triggered when the user presses the Enter key whilst focussing the field. |

---

### File Field

An input used for selecting files.

#### Importing

```tsx
import { FileField } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<FileField />
```

##### With annotation

```tsx
<Annotation
    label="Avatar"
    error="File size is too large">
    <FileField error />
</Annotation>
```

#### API Reference

##### FileField Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `round` | `boolean` | `false` | - |
| `size` | 'xsm' \| 'sml' \| 'med' \| 'lrg' | `med` | - |
| `variant` | 'default' \| 'minimal' | `default` | - |
| `icon` | `React.ReactNode` | - | Icon element displayed on the left side of the field. |
| `error` | `any` | - | Marks the field as invalid when truthy. |
| `loading` | `boolean` | `false` | Shows a loading state on the upload button. |
| `disabled` | `boolean` | `false` | - |

---

### Gradient

An easy beautiful gradient.

#### Importing

```tsx
import { Gradient } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Gradient
    style={{
        width: 400,
        height: 400
    }}
    stops={['#FF6B8A', '#8A6BFF', '#4EECC2', '#4DA8FF']} />
```

##### Mesh gradient

```tsx
<Gradient
    style={{
        width: 400,
        height: 400
    }}
    stops={['#FF6B8A', '#8A6BFF', '#4EECC2', '#4DA8FF']} />
```

#### API Reference

##### Gradient Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `stops` | `string[]` | `required` | An array of color stop values (hex, rgb, etc.). |
| `type` | 'linear' \| 'radial' \| 'mesh' | `linear` | The layout of the gradient. |
| `angle` | `number` | `0` | The angle of the linear gradient in degrees. |
| `noise` | `number` | `0.05` | The opacity of the film grain noise overlay (0 to 1). |
| `meshSeed` | `string` | `'fluid'` | Seed string used to randomly position mesh gradient points. |
| `warp` | `number` | `0` | Amount of distortion to apply to the mesh gradient, using fractal noise. |
| `warpScale` | `number` | `1` | Scale of the fractal noise distortion. |

---

### Group

Merges multiple toggle, button or field inputs.

#### Importing

```tsx
import { Group } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Group>
    <Toggle>
        <LuBold />
    </Toggle>
    <Toggle>
        <LuItalic />
    </Toggle>
    <Toggle>
        <LuUnderline />
    </Toggle>
</Group>
```

##### Usage

```tsx
<Group>
    <Field placeholder="Email" round style={{ width: '10rem' }} />
    <Button round>
        Submit
    </Button>
</Group>
```

#### API Reference

##### Group Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `split` | `boolean` | `false` | Leaves gap spacing between grouped elements. |
| `direction` | 'horizontal' \| 'vertical' | `horizontal` | The layout direction of the grouped elements. |
| `dividers` | `boolean` | `false` | Shows dividers between adjacent elements (only applies when split is false). |

---

### Hamburger

A button which switches between an open and closed state.

#### Importing

```tsx
import { Hamburger } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Hamburger />
```

#### API Reference

##### Hamburger Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `open` | `boolean` | - | Controlled open state. When set, the component is controlled. |
| `color` | `string` | - | Custom color for the hamburger lines. |
| `disabled` | `boolean` | `false` | - |

---

### Indicator

Displays an activity indicator at the corner of an element.

#### Importing

```tsx
import { IndicatorRoot, IndicatorBadge } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<IndicatorRoot>
    <Button>
        <LuShoppingCart />
    </Button>
    <IndicatorBadge outline="var(--f-clr-bg-100)" />
</IndicatorRoot>
```

##### Position and content

```tsx
<IndicatorRoot>
    <Button>
        <LuUser />
    </Button>
    <IndicatorBadge position="bottom" outline="var(--f-clr-bg-100)">
        New
    </IndicatorBadge>
</IndicatorRoot>
```

#### API Reference

##### IndicatorBadge Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `color` | `string` | - | Custom background color for the indicator badge. |
| `outline` | `string` | `none` | Color of the border outline around the indicator. |
| `position` | 'bottom' \| 'top' | `top` | - |

---

### Interactable

Displays a translucent overlay when an element is hovered over or has focus.

#### Importing

```tsx
import { Interactable } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Interactable
    as={Card}
    tabIndex={0}
    background="middle"
    style={{ position: 'relative', width: 200, height: 100 }} />
```

#### API Reference

##### Interactable Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `as` | `React.ElementType` | `button` | Underlying component or element to render as. |
| `noHover` | `boolean` | `false` | Prevents showing a highlight overlay when the user hovers over the element. |
| `highlightColor` | `string` | - | Custom color for the hover/focus highlight overlay. |
| `interactTarget` | `React.RefObject<HTMLElement | null>` | - | Ref of target element that triggers highlight on hover/focus (defaults to self). |
| `disabled` | `boolean` | - | - |

---

### Key

Displays a keyboard input.

#### Importing

```tsx
import { Key } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Key>Ctrl + D</Key>
```

---

### Modal

Displays a container with content overlayed onto the page.

#### Importing

```tsx
import { ModalRoot, ModalContent, ModalFooter } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<ModalRoot show={open} onClose={() => setOpen(false)}>
    <ModalContent title="A modal">
        Modal content.
    </ModalContent>
</ModalRoot>
            
<Button onClick={() => setOpen(!open)}>
    Toggle modal
</Button>
```

##### With footer

```tsx
<ModalRoot
    show={open}
    onClose={() => setOpen(false)}>
    <ModalContent title="Is this a modal?">
        Click confirm or close.
    </ModalContent>
    <ModalFooter>
        <Button compact style={{ marginLeft: 'auto' }}>
            Confirm
        </Button>
    </ModalFooter>
</ModalRoot>
            
<Button onClick={() => setOpen(!open)}>
    Toggle modal
</Button>
```

#### API Reference

##### ModalRoot Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `show` | `boolean` | - | Controlled visibility state of the modal. |
| `onClose` | `() => void` | - | Callback function triggered when the modal should close (e.g. clicking the overlay, close button, or swiping). |
| `mobileClosing` | 'button' \| 'handle' | `handle` | The close interface used on mobile devices. A handle allows the modal to be swiped down to close. |

##### ModalContent Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `title` | `React.ReactNode` | - | The title shown in the modal header. |

---

### Navigation Menu

A horizontal tree of links used for navigation.

#### Importing

```tsx
import { NavigationMenuGroup, NavigationMenuLink, NavigationMenuRoot } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<NavigationMenuRoot style={{ zIndex: 2 }}>
    <NavigationMenuGroup label="Home" />
    <NavigationMenuGroup label="Products" style={{ width: '14rem' }}>
        <Animate
            inherit
            animate={{
                opacity: [0, 1],
                duration: .35,
                delay: .25
            }}>
            <NavigationMenuLink>
                <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--f-spacing-xsm)' }}>
                    <LuCirclePlay /> Lively
                </div>

                <div style={{ fontSize: '.9em', marginTop: 'var(--f-spacing-xsm)' }}>
                    Modern lightweight React animation framework.
                </div>
            </NavigationMenuLink>

            <NavigationMenuLink>
                <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--f-spacing-xsm)' }}>
                    <LuAppWindow /> Fluid UI
                </div>

                <div style={{ fontSize: '.9em', marginTop: 'var(--f-spacing-xsm)' }}>
                    Zero-runtime CSS-in-JS React UI library.
                </div>
            </NavigationMenuLink>
        </Animate>
    </NavigationMenuGroup>
    <NavigationMenuGroup label="Docs" style={{ width: '8rem' }}>
        <Animate
            inherit
            animate={{
                opacity: [0, 1],
                duration: .35,
                delay: .25
            }}>
            <NavigationMenuLink>
                Lively
            </NavigationMenuLink>
            <NavigationMenuLink>
                Fluid UI
            </NavigationMenuLink>
        </Animate>
    </NavigationMenuGroup>
    <NavigationMenuGroup label="About" />
</NavigationMenuRoot>
```

#### API Reference

##### NavigationMenuGroup Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `label` | `React.ReactNode` | - | The text or element shown in the menu bar. |
| `round` | `boolean` | `false` | - |
| `href` | `string` | - | The URL this group link should navigate to if clicked. |
| `target` | '_blank' \| '_parent' \| '_self' \| '_top' | - | Target attribute for the link. |
| `active` | `boolean` | `false` | Shows an active indicator below the group label. |
| `position` | 'start' \| 'center' \| 'end' | `center` | How to align the dropdown menu container. |
| `Link` | `React.ComponentType` | `a` | Custom component or element to render as the trigger link. |

##### NavigationMenuLink Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `as` | `React.ComponentType` | `a` | Custom component or element to render this menu link item as. |

---

### Number Field

An input used for entering numerical values.

#### Importing

```tsx
import { NumberField } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<NumberField />
```

##### With annotation

```tsx
<Annotation
    label="Price">
    <NumberField
        required
        controls={false}
        icon="$" />
</Annotation>
```

#### API Reference

##### NumberField Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `precision` | `number` | `3` | Maximum number of digits to allow after the decimal. |
| `controls` | `boolean` | `true` | Shows increment/decrement controls on the sides of the input field. |
| `size` | 'xsm' \| 'sml' \| 'med' \| 'lrg' | `med` | - |
| `variant` | 'default' \| 'minimal' | `default` | - |
| `round` | `boolean` | `false` | - |
| `icon` | `React.ReactNode` | - | Icon element displayed on the left side of the field. |
| `error` | `any` | - | Marks the field as invalid when truthy. |
| `disabled` | `boolean` | `false` | - |

---

### Overlay

Displays content overlayed onto the page.

#### Importing

```tsx
import { Overlay } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Overlay
    show={open} 
    onClose={() => setOpen(false)}>
    <img width={200} height={200} src="/images/image.png" />
</Overlay>

<Button onClick={() => setOpen(!open)}>
    Toggle overlay
</Button>
```

#### API Reference

##### Overlay Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `show` | `boolean` | - | Controlled visibility state of the overlay. |
| `onClose` | `() => void` | - | Callback function triggered when clicking the tint/backdrop or pressing Escape. |

---

### Pagination

A set of inputs used for navigation between pages.

#### Importing

```tsx
import { Pagination } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Pagination
    pages={29} />
```

#### API Reference

##### Pagination Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `pages` | `number` | `required` | The total number of pages. |
| `defaultPage` | `number` | - | The default page index selected initially (0-indexed). |
| `page` | `number` | - | Controlled page index (0-indexed). |
| `onChange` | `(page: number) => void` | - | Callback triggered when page changes. |
| `compact` | `boolean` | `false` | Hides the numbered page buttons, showing only next/prev arrows. |
| `skipable` | `boolean` | `false` | Shows skip to first and last buttons. |
| `shape` | 'square' \| 'round' \| 'pill' | `square` | - |
| `size` | 'xsm' \| 'sml' \| 'med' \| 'lrg' | `med` | - |
| `variant` | 'default' \| 'neutral' \| 'minimal' | `default` | - |
| `disabled` | `boolean` | `false` | - |
| `color` | `string` | - | Custom color for the selected page indicator. |

---

### Panel

Resizable panels.

#### Importing

```tsx
import { Panel } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Panel
    style={{ width: '200px', height: '200px' }}>
    <div style={{ background: 'var(--f-clr-surface-100)' }} />

    <Panel handles direction="vertical">
        <div style={{ background: 'var(--f-clr-surface-100)' }} />
        <div style={{ background: 'var(--f-clr-surface-100)' }} />
        <div style={{ background: 'var(--f-clr-surface-100)' }} />
    </Panel>
</Panel>
```

#### API Reference

##### Panel Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `variant` | 'default' \| 'minimal' | `default` | - |
| `direction` | 'horizontal' \| 'vertical' | `horizontal` | The direction in which the panels are stacked. |
| `handles` | `boolean` | `true` | Shows draggable resize handles between adjacent panels. |
| `defaultSizes` | `number[]` | - | An array of fractional numbers representing initial size weights for each child panel (adds up to 1). |

---

### Password Field

An input used for entering passwords.

#### Importing

```tsx
import { PasswordField } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<PasswordField />
```

##### With annotation

```tsx
<Annotation
    label="Password"
    error="Password is incorrect">
    <PasswordField error />
</Annotation>
```

#### API Reference

##### PasswordField Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `strengthBar` | `boolean` | `false` | Shows a bar indicating how secure the entered password is. |
| `size` | 'xsm' \| 'sml' \| 'med' \| 'lrg' | `med` | - |
| `variant` | 'default' \| 'minimal' | `default` | - |
| `round` | `boolean` | `false` | - |
| `icon` | `React.ReactNode` | - | Icon element displayed on the left side of the field. |
| `error` | `any` | - | Marks the field as invalid when truthy. |
| `disabled` | `boolean` | `false` | - |

---

### Pincode

An input used for entering numerical codes.

#### Importing

```tsx
import { Pincode } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Pincode
    format={[3, 3]} />
```

##### With annotation

```tsx
<Annotation label="2FA code">
    <Pincode
        format={[1, 2, 3]} />
</Annotation>
```

#### API Reference

##### Pincode Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `round` | `boolean` | `false` | - |
| `size` | 'xsm' \| 'sml' \| 'med' \| 'lrg' | `med` | - |
| `variant` | 'default' \| 'minimal' | `default` | - |
| `format` | `number[]` | `[1, 1, 1, 1]` | An array of numbers indicating how many inputs to show. A single digit represents grouped inputs; multiple digits represent spaced-apart inputs. |
| `masked` | `boolean` | - | Hides the entered pincode input. |
| `value` | `string` | - | Controlled pincode value. |
| `defaultValue` | `string` | - | Default pincode value for uncontrolled usage. |
| `error` | `any` | - | Marks the pincode as invalid when truthy. |
| `onChange` | `(value: string) => void` | - | - |
| `disabled` | `boolean` | `false` | - |

---

### Popover

Displays a popup with content when a trigger is clicked.

#### Importing

```tsx
import { PopoverContent, PopoverRoot, PopoverTrigger } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<PopoverRoot>
    <PopoverTrigger>
        <Button>
            Open info
        </Button>
    </PopoverTrigger>

    <PopoverContent>
        <Card elevated>
            I'm a popover!
        </Card>
    </PopoverContent>
</PopoverRoot>
```

#### API Reference

##### PopoverRoot Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `position` | 'auto' \| 'center' | `auto` | How to position the popover content relative to the trigger. |
| `mobileContainer` | 'popover' \| 'modal' | `popover` | How to display the popover on mobile devices. |
| `stretch` | `boolean` | `false` | Whether to stretch the popover container width to match the trigger element. |
| `onClose` | `() => void` | - | Callback function triggered when the popover closes. |

##### PopoverTrigger Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `longpress` | `boolean` | `false` | Requires holding the trigger down for at least 400ms to open the popover. |
| `disabled` | `boolean` | `false` | - |

---

### Progress Bar

An indicator displaying the progress of something.

#### Importing

```tsx
import { ProgressBar } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<ProgressBar />
```

#### API Reference

##### ProgressBar Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `size` | 'xsm' \| 'sml' \| 'med' \| 'lrg' | `med` | - |
| `value` | `number` | - | The progress value between 0 and 1. |
| `color` | `string` | - | Custom background color for the progress bar indicator. |

---

### Radio

A selectable input, of which 1 must be selected at all times within a group.

#### Importing

```tsx
import { Radio } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Radio />
```

##### Grouped

```tsx
<div style={{ display: 'flex', gap: 'var(--f-spacing-sml)' }}>
    <Radio name="grouped" defaultChecked />
    <Radio name="grouped" />
    <Radio name="grouped" />
</div>
```

#### API Reference

##### Radio Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `size` | 'xsm' \| 'sml' \| 'med' \| 'lrg' | `med` | - |
| `color` | `string` | - | Custom accent color for the radio when checked. |
| `error` | `any` | - | Marks the radio as invalid when truthy. |
| `disabled` | `boolean` | `false` | - |

---

### Scrollarea

A scrollable container.

#### Importing

```tsx
import { Scrollarea } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Scrollarea style={{ width: 128, height: 64 }}>
    <div style={{ whiteSpace: 'nowrap' }}>
        Lorem, ipsum dolor sit amet consectetur <br />
        adipisicing elit. Eaque accusantium repellat, <br />
        delectus quidem omnis eligendi? Earum <br />
        voluptatem mollitia voluptatibus accusamus <br />
        dolorum, repellendus nisi. Nobis error aut <br />
        maxime laborum! Nobis, pariatur.
    </div>
</Scrollarea>
```

#### API Reference

##### Scrollarea Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `direction` | 'vertical' \| 'horizontal' | `vertical` | The scroll direction of the container. |
| `variant` | 'hover' \| 'permanent' | `hover` | Whether scrollbars are shown permanently or only when hovering. |
| `behavior` | 'normal' \| 'shift' | `normal` | For shift behavior, scrolling with the scrollwheel requires holding Shift. |
| `disabled` | `boolean` | `false` | Disables custom scrollbars, reverting to native overflow behavior. |

---

### Segmented

An input with multiple options of which only 1 can be selected at a time.

#### Importing

```tsx
import { Segmented } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Segmented
    options={[
        { label: 'Light', value: 'light' },
        { label: 'Dark', value: 'dark' },
        { label: 'Retro', value: 'retro' }
    ]} />
```

##### With tooltips

```tsx
<Segmented
    options={[
        { label: <LuSun />, value: 'light', tooltip: 'Light' },
        { label: <LuMoon />, value: 'dark', tooltip: 'Dark' }
    ]} />
```

#### API Reference

##### Segmented Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `round` | `boolean` | `false` | - |
| `size` | 'sml' \| 'med' \| 'lrg' | `med` | - |
| `variant` | 'default' \| 'neutral' \| 'minimal' | `default` | - |
| `options` | `{ label: React.ReactNode; value: string | number; disabled?: boolean; tooltip?: string; }[]` | `required` | The list of options to display. |
| `uniform` | `boolean` | `false` | Makes all entries equal size regardless of their content. |
| `vertical` | `boolean` | `false` | Stacks the options vertically. |
| `value` | 'string' \| 'number' | - | Controlled selected value. |
| `defaultValue` | 'string' \| 'number' | - | Default selected value for uncontrolled usage. |
| `onChange` | `(value: string | number) => void` | - | - |
| `error` | `any` | - | Marks the segmented control as invalid when truthy. |

---

### Select

Displays a list of selectable options.

#### Importing

```tsx
import { Select } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Select
    icon={<LuPalette />}
    options={[
        { label: 'Light', value: 'light' },
        { label: 'Dark', value: 'dark' },
        { label: 'Retro', value: 'retro' },
        { label: 'Secret', value: 'secret', disabled: true }
    ]} />
```

##### With annotation

```tsx
<Annotation label="Theme">
    <Select
        required
        icon={<LuPalette />}
        options={[
            { label: 'Light', value: 'light' },
            { label: 'Dark', value: 'dark' },
            { label: 'Retro', value: 'retro' },
            { label: 'Secret', value: 'secret', disabled: true }
        ]} />
</Annotation>
```

##### Virtualization

```tsx
<Select
    searchable
    icon={<LuList />}
    virtualItemHeight={36}
    options={new Array(500).fill(0).map((_, i) => ({ label: `Item ${i + 1}`, value: i }))} />
```

#### API Reference

##### Select Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `options` | `{ label: React.ReactNode; value: T extends string | number | string[]; key?: string; disabled?: boolean; }[]` | `required` | The list of options to display. |
| `variant` | 'default' \| 'inverted' \| 'minimal' | `default` | - |
| `searchable` | `boolean` | `false` | Enables a search field in the dropdown. |
| `limit` | `number` | - | Maximum number of options that can be selected at a time when multiple is true. |
| `emptyMessage` | `string` | `"Nothing found"` | Text shown when no options match the search. |
| `contentSize` | 'xsm' \| 'sml' \| 'med' \| 'lrg' | `med` | Size of the dropdown content. |
| `mobileContainer` | 'popover' \| 'modal' | `popover` | How to display the Select content on mobile devices. |
| `virtualItemHeight` | `number` | - | When set to a number greater than 0, enables virtual scrolling for better performance with large option lists. |
| `value` | `T` | - | Controlled selected value or array of values. |
| `defaultValue` | `T` | - | Default selected value or array of values. |
| `onChange` | `(value: T) => void` | - | Callback function triggered when selection changes. |
| `disabled` | `boolean` | `false` | - |

---

### Sidebar

A collapsible sidebar.

#### Importing

```tsx
import { SidebarHeading, SidebarItem, SidebarRoot, SidebarToggle, SidebarUser } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<SidebarRoot
    collapsed={collapsed}
    setCollapsed={setCollapsed}
    style={{
        width: '16rem',
        height: '48rem',
        backgroundColor: 'var(--f-clr-surface-100)',
        paddingBlock: '1rem',
        borderRadius: 'var(--f-radius-med)'
    }}>
    <SidebarToggle>
        <LuGithub />
    </SidebarToggle>

    <SidebarHeading style={{
        paddingTop: 'var(--f-spacing-lrg)',
        paddingBottom: 'var(--f-spacing-xsm)'
    }}>
        My account
    </SidebarHeading>

    <SidebarItem label="Home" icon={<LuHouse />} active />
    <SidebarItem label="Settings" icon={<LuSettings />}>
        <SidebarItem label="General" icon={<LuGlobe />} size="sml" />
        <SidebarItem label="Security" icon={<LuShield />} size="sml" />
        <SidebarItem label="Payment" icon={<LuCreditCard />} size="sml" />
    </SidebarItem>
    <SidebarItem label="Orders" icon={<LuPackage />} />

    <ActionMenuRoot stretch>
        <ActionMenuTrigger>
            <SidebarUser name="John Doe" style={{ marginTop: 'auto' }} />
        </ActionMenuTrigger>

        <ActionMenuMenu>
            <ActionMenuItem>
                <LuLogOut />
                Sign out
            </ActionMenuItem>
        </ActionMenuMenu>
    </ActionMenuRoot>
</SidebarRoot>
```

##### Tree navigation

```tsx
<div>
    <SidebarItem label="Cars" compact>
        <SidebarItem label="Audio" compact />
        <SidebarItem label="BMW" compact />
        <SidebarItem label="Mercedes" compact />
    </SidebarItem>
    <SidebarItem label="Rockets" compact>
        <SidebarItem label="Saturn V" compact />
        <SidebarItem label="Spaceshuttle" compact />
        <SidebarItem label="SLS" compact />
        <SidebarItem label="SpaceX" compact>
            <SidebarItem label="Falcon 9" compact />
            <SidebarItem label="Falcon Heavy" compact />
            <SidebarItem label="Starship" compact />
        </SidebarItem>
    </SidebarItem>
</div>
```

#### API Reference

##### SidebarRoot Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `collapsed` | `boolean` | - | Whether the sidebar is collapsed. |
| `setCollapsed` | `(value: boolean) => void` | - | Callback function triggered when the collapsed state changes. |

##### SidebarToggle Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `toggle` | 'square' \| 'round' \| 'none' | `square` | The visual style of the toggle button. |

##### SidebarItem Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `label` | `string` | - | The text label displayed on the item. |
| `icon` | `React.ReactNode` | - | An optional icon displayed on the left. |
| `right` | `React.ReactNode` | - | Custom element shown on the right side of the label when there are no child items. |
| `size` | 'sml' \| 'med' | `med` | - |
| `active` | `boolean` | `false` | Marks the item as currently selected. |
| `variant` | 'default' \| 'inverted' | `default` | - |
| `round` | `boolean` | `false` | - |
| `compact` | `boolean` | `false` | Renders a smaller, compact variant of the item. |
| `defaultOpen` | `boolean` | `false` | Whether the nested child items are expanded by default. |

##### SidebarUser Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `name` | `string` | - | The name of the user. |
| `status` | `string` | - | An optional status message shown below the user name. |
| `indicator` | `string | number | boolean` | `false` | Visual status indicator badge content shown over the avatar. |
| `round` | `boolean` | `false` | Makes the user avatar round. |
| `icon` | `React.ReactNode` | - | Action icon shown on the right (defaults to a "more options" icon). |

---

### Skeleton

Used to show a placeholder while content is loading.

#### Importing

```tsx
import { Skeleton } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Skeleton />
```

##### Aspect ratio

```tsx
<Skeleton />
```

#### API Reference

##### Skeleton Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `w` | 'number' \| 'string' | - | The width of the skeleton loader. |
| `h` | 'number' \| 'string' | - | The height of the skeleton loader. |
| `ar` | `number` | - | The aspect ratio of the skeleton loader. |
| `radius` | 'xsm' \| 'sml' \| 'med' \| 'lrg' \| 'max' | `sml` | The border radius size. |

---

### Slider

An input that allows for selecting 1 or multiple values from a given range.

#### Importing

```tsx
import { Slider } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Slider
    max={140}
    step={5}
    formatTooltip={value => `${value}db`}
    defaultValue={[60]} />
```

#### API Reference

##### Slider Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `handles` | `number` | `1` | The number of handles this slider should have. |
| `vertical` | `boolean` | `false` | Renders the slider vertically. |
| `tooltips` | 'never' \| 'interact' \| 'always' | `interact` | When to display a tooltip above each handle. |
| `formatTooltip` | `(value: number) => string` | - | Custom formatter function for the tooltip value. |
| `label` | `string` | - | Label displayed above the slider track. |
| `value` | `number[]` | - | Controlled values for each handle. |
| `defaultValue` | `number[]` | - | Default values for uncontrolled usage. |
| `onChange` | `(values: number[]) => void` | - | - |
| `disabled` | `boolean` | `false` | - |

---

### Spinner

A spinning loading indicator.

#### Importing

```tsx
import { Spinner } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Spinner />
```

#### API Reference

##### Spinner Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `color` | `string` | - | Custom stroke color for the spinner animation. |

---

### Stepper

An ordered list of completable steps.

#### Importing

```tsx
import { Stepper } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Stepper
    steps={[
        {
            name: 'Address',
            icon: <LuBuilding />
        },
        {
            name: 'Shipping',
            icon: <LuTruck />,
            error: true
        },
        {
            name: 'Payment',
            icon: <LuCreditCard />
        }
    ]} />
```

#### API Reference

##### Stepper Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `steps` | `{ name: string; icon: React.ReactNode; label?: string; error?: boolean; }[]` | - | An array of steps configs. label defaults to a 0-padded index. |
| `completed` | `number` | - | The number of completed steps (0-indexed). |
| `setCompleted` | `(value: number) => void` | - | Callback function triggered when clicking a navigatable step. |
| `navigation` | 'none' \| 'forwards' \| 'backwards' \| 'both' | `backwards` | Controls which steps are navigatable relative to the current completed step. |
| `variant` | 'default' \| 'compact' \| 'vertical' | `default` | - |

---

### Swatch

Displays one or multiple colors.

#### Importing

```tsx
import { Swatch } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Swatch />
```

##### Multiple colors

```tsx
<Swatch 
    color={[
        'var(--f-clr-primary-100)', 
        'var(--f-clr-surface-200)'
    ]} />
```

#### API Reference

##### Swatch Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `round` | `boolean` | `false` | - |
| `size` | 'xsm' \| 'sml' \| 'med' \| 'lrg' | `med` | - |
| `color` | 'string' \| 'string[]' | `['transparent']` | A single color or an array of colors to display in segments. |

---

### Switch

An input that switches between an on and off state.

#### Importing

```tsx
import { Switch } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Switch />
```

##### With icons

```tsx
<Switch
    size="lrg"
    iconOff={<LuMoon />}
    iconOn={<LuSun />} />
```

#### API Reference

##### Switch Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `size` | 'xsm' \| 'sml' \| 'med' \| 'lrg' | `med` | - |
| `color` | `string` | - | Custom accent color for the switch when checked. |
| `round` | `boolean` | `true` | - |
| `error` | `any` | - | Marks the switch as invalid when truthy. |
| `iconOn` | `React.ReactNode` | - | Icon shown in the on/checked position. |
| `iconOff` | `React.ReactNode` | - | Icon shown in the off/unchecked position. |
| `disabled` | `boolean` | `false` | - |

---

### Table

A table displaying data.

#### Importing

```tsx
import { Table } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Table 
    data={[
        { id: 0, value: 2, date: '29-10-${new Date().getFullYear()}' },
        { id: 1, value: 3, date: '19-01-${new Date().getFullYear()}' },
        { id: 2, value: 5, date: '22-04-${new Date().getFullYear()}' }
    ]} />
```

##### Column formatters

```tsx
<Table
    columns={['id', 'value', 'date']}
    data={[
        { id: 0, value: 2, date: '29-10-${new Date().getFullYear()}' },
        { id: 1, value: 3, date: '19-01-${new Date().getFullYear()}' },
        { id: 2, value: 5, date: '22-04-${new Date().getFullYear()}' }
    ]}
    rowActions={row => [
        <ActionMenuItem key={0}>
            <LuSquareMousePointer />
            Inspect #{row.id}
        </ActionMenuItem>,
        <ActionMenuItem key={1}>
            <LuUndo />
            Refund \${row.value.toFixed(2)}
        </ActionMenuItem>
    ]}/>
```

##### Empty Table

```tsx
<Table
    columns={['user', 'points', 'eliminated']}
    data={[]}
    emptyMessage="Oop no data here!" />
```

#### API Reference

##### Table Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `data` | `(T extends { [key: string]: string | number | Date; })[]` | `required` | The array of row data objects to display. |
| `columns` | `(keyof T)[]` | `required` | The keys of row data objects that represent columns. |
| `maxColumnWidth` | `string` | `auto` | The maximum width of a table column. |
| `selectable` | `boolean` | `false` | Allows rows to be selected using checkboxes. |
| `sortable` | 'boolean' \| '(keyof T)[]' | `false` | Enables sorting columns when clicked. Can specify an array of sortable column keys. |
| `selected` | `number[]` | - | Controlled array of selected row indices. |
| `onSelect` | `(selected: number[]) => void` | - | Callback function triggered when row selection changes. |
| `columnFormatters` | `{ [column in keyof T]: (value: T[column]) => React.ReactNode }` | - | Custom formatting functions for specific columns. |
| `rowActions` | `(row: T, index: number) => React.ReactNode` | - | A function that returns action menu items for a row. |
| `emptyMessage` | `string` | `"Nothing to display"` | Text shown when the table data is empty. |

---

### Tabs

An input with multiple options of which only 1 can be selected at a time.

#### Importing

```tsx
import { Tabs } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Tabs
    options={[
        { label: 'Home', value: 'home' },
        { label: 'Settings', value: 'settings' },
        { label: 'Orders', value: 'orders' },
        { label: 'Danger zone', value: 'danger', disabled: true }
    ]} />
```

#### API Reference

##### Tabs Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `options` | `{ label: string; value: (T extends string | number | string[]); disabled?: boolean; panelId?: string; }[]` | `required` | The array of tab options. |
| `variant` | 'default' \| 'minimal' | `default` | - |
| `value` | `T` | - | Controlled value of the currently selected tab. |
| `defaultValue` | `T` | - | Default selected tab value. |
| `onChange` | `(value: T) => void` | - | Callback function triggered when tab selection changes. |

---

### Textarea

A form textarea.

#### Importing

```tsx
import { Textarea } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Textarea />
```

#### API Reference

##### Textarea Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `size` | 'xsm' \| 'sml' \| 'med' \| 'lrg' | `med` | - |
| `variant` | 'default' \| 'minimal' | `default` | - |
| `error` | `any` | - | Marks the textarea as invalid when truthy. |
| `resize` | 'none' \| 'vertical' \| 'horizontal' \| 'both' \| 'auto' | `both` | Controls how the textarea can be resized. A value of auto allows the textarea to grow with its contents. |
| `disabled` | `boolean` | `false` | - |

---

### Theme Toggle

A toggle button which switches between a light and dark color theme.

#### Importing

```tsx
import { ThemeToggle } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<ThemeToggle />
```

#### API Reference

##### ThemeToggle Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `size` | 'xsm' \| 'sml' \| 'med' \| 'lrg' | `med` | - |
| `variant` | 'default' \| 'minimal' \| 'neutral' | `default` | - |
| `compact` | `boolean` | `false` | - |
| `round` | `boolean` | `false` | - |
| `disabled` | `boolean` | `false` | - |

---

### Ticker

Animated text/number display.

#### Importing

```tsx
import { Ticker } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Ticker
    style={{ fontSize: '3rem' }} />
```

#### API Reference

##### Ticker Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `value` | 'string' \| 'number' | `required` | - |
| `fadeEdges` | `boolean` | `true` | Apply a subtle fade in and out effect along the top and bottom edges. |
| `interpolateNumbers` | `boolean` | `false` | When true, adds intermediate values when animating between different numbers. |
| `selective` | `boolean` | `false` | When true, only animate characters that have actually changed since the last value. |
| `lineHeight` | `number` | `1.1` | - |
| `duration` | `number` | `0.4` | The animation duration of each character transition in seconds. |
| `stagger` | `number` | `0.05` | Stagger delay between sequential character animations in seconds. |

---

### Time Field

An input used for entering numerical values.

#### Importing

```tsx
import { TimeField } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<TimeField />
```

#### API Reference

##### TimeField Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `min` | `string` | - | Minimum time specified in 24H-based hh:mm format. |
| `max` | `string` | - | Maximum time specified in 24H-based hh:mm format. |
| `locale` | `string` | - | A language and/or region identifier, determining the displayed language. |
| `round` | `boolean` | `false` | - |
| `size` | 'xsm' \| 'sml' \| 'med' \| 'lrg' | `med` | - |
| `variant` | 'default' \| 'minimal' | `default` | - |
| `icon` | `React.ReactNode` | - | Icon element displayed on the left side of the field. |
| `error` | `any` | - | Marks the field as invalid when truthy. |
| `disabled` | `boolean` | `false` | - |

---

### Timeline

An ordered timeline of events.

#### Importing

```tsx
import { Timeline } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Timeline>
    <div>1. Big bang</div>
    <div>2. Formation of the Earth</div>
    <div>3. Creation of Fluid UI</div>
</Timeline>
```

#### API Reference

##### Timeline Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `active` | `number` | `0` | The number of events currently active/completed. |
| `direction` | 'horizontal' \| 'vertical' | `horizontal` | - |
| `uniform` | `boolean` | `false` | Whether all events should have equal size regardless of content. |
| `reverse` | `boolean` | `false` | Show timeline completion in reverse order. |
| `overflow` | `boolean` | `false` | Allows the content of the last timeline event to overflow past its bullet point. |

---

### Toast

Used to display a temporary message to a user.

#### Importing

```tsx
import { Toast } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Toast
    icon={<LuCircleAlert />} />
```

##### With description and custom action

```tsx
<Toast
    title="Error"
    icon={<LuTriangleAlert />}
    color="red"
    action="Dismiss">
    Something went wrong.
</Toast>
```

#### API Reference

##### Toast Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `round` | `boolean` | `false` | - |
| `title` | `string` | - | The main title heading text. |
| `color` | `string` | - | Custom background color for the icon container badge. |
| `icon` | `React.ReactNode` | - | Icon displayed on the left side of the toast. |
| `action` | `React.ReactNode` | `<Icon type="close" />` | Custom dismiss button content displayed on the right. |
| `onClose` | `() => void` | - | Callback function triggered when the toast is closed/dismissed. |

---

### Toggle

A button which cycles between 2 or more states.

#### Importing

```tsx
import { Toggle } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Toggle>
    <LuBold />
    <LuItalic />
</Toggle>
```

##### Cycle through

```tsx
<Toggle>
    <LuBold />
    <LuItalic />
    <LuUnderline />
</Toggle>
```

#### API Reference

##### Toggle Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `size` | 'xsm' \| 'sml' \| 'med' \| 'lrg' | `med` | - |
| `variant` | 'default' \| 'minimal' \| 'neutral' | `default` | - |
| `transition` | 'slide' \| 'morph' | `slide` | Transition animation used when switching between states. |
| `compact` | `boolean` | `false` | - |
| `round` | `boolean` | `false` | - |
| `disabled` | `boolean` | `false` | - |

---

### Tooltip

Displays an information popup next to an element when that element is hovered or receives focus.

#### Importing

```tsx
import { Tooltip } from '@infinityfx/fluid';
```

#### Examples

##### Usage

```tsx
<Tooltip>
    <Button>
        <LuRocket />
    </Button>
</Tooltip>
```

##### Groups

```tsx
<Group>
    <Tooltip content="Bold">
        <Button variant="neutral">
            <LuBold />
        </Button>
    </Tooltip>
    <Tooltip content="Italic">
        <Button variant="neutral">
            <LuItalic />
        </Button>
    </Tooltip>
    <Tooltip content="Underline">
        <Button variant="neutral">
            <LuUnderline />
        </Button>
    </Tooltip>
</Group>
```

#### API Reference

##### Tooltip Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `variant` | 'default' \| 'inverted' | `default` | - |
| `content` | `React.ReactNode` | - | The content (text or elements) to display inside the tooltip popup. |
| `position` | 'auto' \| 'top' \| 'left' \| 'bottom' \| 'right' | `auto` | How to position the tooltip relative to its trigger child. |
| `delay` | `number` | `0.3` | Hover delay in seconds before the tooltip opens. |
| `visibility` | 'never' \| 'interact' \| 'always' | `interact` | When to show the tooltip. |

---