> For the complete documentation index, see [llms.txt](https://dirkscripts.gitbook.io/dirkscripts-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dirkscripts.gitbook.io/dirkscripts-documentation/resources/dirk-cfx-react/components.md).

# Components

All components are exported from `dirk-cfx-react` and use Mantine + Framer Motion internally. They follow a dark-theme, VH-based sizing convention.

***

## Admin Components

### AdminPageTitle

Section header for admin panel pages. Renders a Lucide icon with a localized uppercase title.

```tsx
import { AdminPageTitle } from "dirk-cfx-react";
import { Fish } from "lucide-react";

<AdminPageTitle title="FishSettings" icon={Fish} color="#4ade80" />
```

| Prop    | Type                         | Description                   |
| ------- | ---------------------------- | ----------------------------- |
| `title` | `string`                     | Locale key for the title text |
| `icon`  | `ComponentType<LucideProps>` | Lucide icon component         |
| `color` | `string`                     | Icon colour                   |

### AsyncSaveButton

Animated save button with idle / pending / success / error states. Shows a spinner while saving, a check on success, and an X on failure.

```tsx
import { AsyncSaveButton } from "dirk-cfx-react";

<AsyncSaveButton
  onSave={async () => {
    const result = await updateSettings(changes);
    return result;
  }}
  color="#4ade80"
  label="Save Changes"
/>
```

| Prop     | Type                 | Description                                                          |
| -------- | -------------------- | -------------------------------------------------------------------- |
| `onSave` | `() => Promise<any>` | Async save handler — return `{ success: false }` to show error state |
| `color`  | `string`             | Theme colour for the button                                          |
| `label`  | `string`             | Button label (default: `"Save Changes"`)                             |
| `style`  | `CSSProperties`      | Optional inline styles                                               |

***

## Input Components

### InputContainer

Styled wrapper for form fields. Provides a title, description, error display, and consistent dark-theme styling.

```tsx
import { InputContainer } from "dirk-cfx-react";

<InputContainer
  title="Fish Name"
  description="The item name used in inventory"
  error={errors?.name}
>
  <TextInput value={name} onChange={...} />
</InputContainer>
```

| Prop           | Type               | Description                                |
| -------------- | ------------------ | ------------------------------------------ |
| `title`        | `string`           | Field label                                |
| `description`  | `string`           | Help text shown below the label            |
| `error`        | `string`           | Validation error message                   |
| `children`     | `ReactNode`        | The input element(s)                       |
| `w`            | `string \| number` | Width (default: `"100%"`)                  |
| `flex`         | `number \| string` | Flex value                                 |
| `bg`           | `string`           | Background colour override                 |
| `p`            | `string \| number` | Padding (default: `"sm"`)                  |
| `rightSection` | `ReactNode`        | Content rendered to the right of the title |
| `variants`     | `Variants`         | Framer Motion variants                     |

### SelectItem

Item selector with image previews. Pulls items from the `useItems` store (populated by `GET_ITEMS` NUI callback).

```tsx
import { SelectItem } from "dirk-cfx-react";

<SelectItem
  label="RewardItem"
  value={selectedItem}
  onChange={(v) => setValue("reward.item", v)}
  excludeItemNames={["weapon_pistol"]}
/>
```

| Prop               | Type                      | Description                         |
| ------------------ | ------------------------- | ----------------------------------- |
| `label`            | `string`                  | Locale key for the select label     |
| `value`            | `string`                  | Currently selected item name        |
| `onChange`         | `(value: string) => void` | Change handler                      |
| `excludeItemNames` | `string[]`                | Item names to exclude from the list |

### FiveMKeyBindInput

Compound component for configuring FiveM keybinds. Supports keyboard, mouse, gamepad, joystick, and touchpad input mappers.

```tsx
import { FiveMKeyBindInput, type FiveMControls } from "dirk-cfx-react";

const [controls, setControls] = useState<FiveMControls>({
  _type: "KEYBOARD",
  _key: "E",
});

<FiveMKeyBindInput value={controls} onChange={setControls}>
  <FiveMKeyBindInput.Category label="Input Type" />
  <FiveMKeyBindInput.Key label="Key" />
</FiveMKeyBindInput>
```

**Sub-components:**

| Component                    | Description                                                                          |
| ---------------------------- | ------------------------------------------------------------------------------------ |
| `FiveMKeyBindInput` (Root)   | Context provider — requires `value` and `onChange`                                   |
| `FiveMKeyBindInput.Category` | Dropdown to select the input mapper (keyboard, mouse, pad, etc.)                     |
| `FiveMKeyBindInput.Key`      | Dropdown for the specific key — auto-filters to valid keys for the selected category |

***

## Modals

### Modal

General-purpose modal with dark theme, header with icon/badge, close button, and description area.

```tsx
import { Modal } from "dirk-cfx-react";

<Modal
  title="Edit Fish"
  icon={Fish}
  iconColor="#4ade80"
  description="Configure this fish species"
  onClose={() => setOpen(false)}
>
  {/* content */}
</Modal>
```

| Prop           | Type                | Description                               |
| -------------- | ------------------- | ----------------------------------------- |
| `title`        | `string`            | Modal title                               |
| `icon`         | `React.ElementType` | Header icon                               |
| `iconColor`    | `string`            | Icon colour                               |
| `description`  | `string`            | Description text below header             |
| `badge`        | `{ label, color }`  | Optional badge next to the title          |
| `onClose`      | `() => void`        | Close handler                             |
| `width`        | `string`            | Modal width (default: `"52vh"`)           |
| `maxHeight`    | `string`            | Max height (default: `"85vh"`)            |
| `zIndex`       | `number`            | Z-index (default: `100`)                  |
| `clickOutside` | `boolean`           | Close on backdrop click (default: `true`) |

### ConfirmModal

Destructive action confirmation with optional type-to-confirm.

```tsx
import { ConfirmModal } from "dirk-cfx-react";

<ConfirmModal
  title="Delete Fish"
  description="This will permanently remove this fish species."
  confirmLabel="Delete"
  confirmText="bass"
  onConfirm={() => removeFish("bass")}
  onClose={() => setOpen(false)}
/>
```

| Prop           | Type         | Description                                                |
| -------------- | ------------ | ---------------------------------------------------------- |
| `title`        | `string`     | Warning title                                              |
| `description`  | `string`     | Warning message                                            |
| `confirmLabel` | `string`     | Confirm button text (default: `"Delete"`)                  |
| `confirmText`  | `string`     | If set, user must type this exact string to enable confirm |
| `onConfirm`    | `() => void` | Confirm handler                                            |
| `onClose`      | `() => void` | Cancel/close handler                                       |

***

## Display Components

### LevelBanner / LevelPanel

XP and level display components. Use with `createSkill` to define your levelling curve.

### Counter

Animated number counter with configurable duration and format.

### BorderedIcon

Icon with a bordered circular background, commonly used in lists.

### FloatingParticles

Decorative animated particle effect for backgrounds.

### InfoBox

Styled information box with icon and text.

### Navigation

Tab-style navigation bar with animated active indicator.

### Title

Styled page title with gradient underline.

### SegmentedControl / SegmentedProgress

Animated segmented controls and progress indicators.