# rn-create-record-dialog
URL: /docs/native/docyrus/create-record-dialog

Bottom-sheet dialog for quick record creation — selectors with dependent clearing, @ / # mentions, AI action chips, toggles and create-more.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-create-record-dialog
```

## Usage

```tsx
import { CreateRecordDialog } from '@/components/docyrus-native/create-record-dialog';

}
  headerLabel="New Task"
  headerFields={[
    {
      key: 'project',
      label: 'Project',
      options: projects,
      clearsFields: ['milestone']
    },
    { key: 'milestone', label: 'Milestone', options: milestones }
  ]}
  mentionTriggers={[{ trigger: '@', options: users }]}
  aiActions={[{ id: 'summarize', label: 'Summarize', onAction: ({ subject }) => summarize(subject) }]}
  footerToggles={[{ key: 'notify', label: 'Notify assignee', defaultChecked: true }]}
  enableCreateMore
  onSubmit={data => api.create(data)} />
```

## API Reference

### CreateRecordDialogProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `open` | `boolean` | `false` | Controlled open state (the form resets on every open) |
| `onOpenChange` | `(open: boolean) => void` | — | Open state change |
| `children` | `ReactNode` | — | Trigger — pressing it opens the dialog |
| `headerIcon` | `ReactNode` | — | Icon before the title |
| `headerLabel` | `string` | — | Title (after `dialogTitle`) |
| `headerFields` | `SelectorFieldConfig[]` | `[]` | Selectors above the subject |
| `subjectPlaceholder` | `string` | `ui.createRecord.subjectPlaceholder` | Subject placeholder |
| `descriptionPlaceholder` | `string` | `ui.createRecord.descriptionPlaceholder` | Description placeholder |
| `descriptionExpanded` | `boolean` | `false` | Show the description input immediately |
| `footerFields` | `SelectorFieldConfig[]` | `[]` | Selectors below the description |
| `footerToggles` | `FooterToggleConfig[]` | `[]` | Switch rows |
| `mentionTriggers` | `MentionTriggerConfig[]` | `[]` | `@` / `#` autocomplete in subject + description |
| `onMentionSelect` | `(selection: MentionSelection) => void` | — | Mention picked |
| `aiActions` | `AiAction[]` | `[]` | AI action chips (`onAction({ subject, description })`) |
| `enableCreateMore` | `boolean` | `false` | Show the create-more switch |
| `createMoreResetKeys` | `string[]` | `['subject', 'description']` | Keys reset after a create-more submit (field keys allowed) |
| `onSubmit` | `(data: CreateRecordFormData) => void \| Promise<void>` | — | Submit handler (required) |
| `isPending` | `boolean` | `false` | Submitting state |
| `saveLabel` | `string` | `ui.createRecord.save` (“Save”) | Submit label |
| `cancelLabel` | `string` | `ui.createRecord.cancel` | Cancel label |
| `createMoreLabel` | `string` | `ui.createRecord.createMore` | Create-more label |
| `addDescriptionLabel` | `string` | `ui.createRecord.addDescription` | Add-description label |
| `dialogTitle` | `string` | `ui.createRecord.dialogTitle` | Title |
| `className` | `string` | — | Sheet class |

### SelectorFieldConfig

| Field | Type | Description |
|------|------|-------------|
| `key` | `string` | Field key (in `data.fields`) |
| `label` | `string` | Label |
| `placeholder` | `string` | Empty text |
| `icon` | `ReactNode` | Icon beside the label |
| `options` | `SelectorOption[]` | Options |
| `value` | `string \| null` | Controlled value |
| `defaultValue` | `string` | Initial value |
| `searchPlaceholder` | `string` | Search placeholder (> 6 options) |
| `emptyText` | `string` | No-results text |
| `onChange` | `(value: string \| null) => void` | Change callback |
| `clearsFields` | `string[]` | Selector keys reset to `null` when this one changes |

### SelectorOption

| Field | Type | Description |
|------|------|-------------|
| `id` | `string` | Value |
| `label` | `string` | Label |
| `description` | `string` | Secondary line (native) |
| `icon` | `ReactNode` | Leading icon |
| `color` | `string` | Dot color (hex / rgb / Tailwind name) |

### FooterToggleConfig

| Field | Type | Description |
|------|------|-------------|
| `key` | `string` | Toggle key (in `data.toggles`) |
| `label` | `string` | Label |
| `defaultChecked` | `boolean` | Initial state |
| `defaultValue` | `boolean` | Deprecated alias of `defaultChecked` |

### MentionTriggerConfig / MentionOption / MentionSelection

| Type | Fields |
|------|--------|
| `MentionTriggerConfig` | `trigger`, `options: MentionOption[]`, `searchPlaceholder?`, `emptyText?` |
| `MentionOption` | `id`, `label`, `description?`, `icon?` |
| `MentionSelection` | `trigger`, `option`, `field: 'subject' \| 'description'` |

Picking a mention removes the typed `@query` and adds a removable chip; selections are returned in `data.mentions`.

### AiAction

| Field | Type | Description |
|------|------|-------------|
| `id` | `string` | Key |
| `label` | `string` | Chip label |
| `icon` | `ReactNode` | Chip icon |
| `disabled` | `boolean` | Disable the chip |
| `onAction` | `(ctx: { subject; description }) => void \| Promise<void>` | Handler |

### CreateRecordFormData

| Field | Type | Description |
|------|------|-------------|
| `subject` | `string` | Trimmed subject |
| `description` | `string` | Trimmed description |
| `fields` | `Record<string, string \| null>` | Selector values |
| `toggles` | `Record<string, boolean>` | Toggle values |
| `mentions` | `MentionSelection[]` | Picked mentions |

## Type Exports

| Type | Description |
|------|-------------|
| `CreateRecordDialogProps` | Props |
| `CreateRecordFormData` | Submit payload |
| `SelectorFieldConfig`, `SelectorOption` | Selectors |
| `FooterToggleConfig` | Toggles |
| `MentionTriggerConfig`, `MentionOption`, `MentionSelection` | Mentions |
| `AiAction` | AI chips |

## Breaking changes (web-parity release)

- `CreateRecordFormData.mentions` added; default save label is “Save” (was “Create”).
- The form resets when the dialog opens (was: on close).
- `FooterToggleConfig.defaultValue` is deprecated in favour of `defaultChecked`.