# Core/DateRangePickerField - Usage

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `helperText` | `string` | No | `--` | Helper text below the field. Replaced by error message when status is error. Use for requirements, disclaimers. |
| `label` | `string` | No | `--` | Label for the field. Required for accessibility; use aria-label if another element acts as label. |
| `layout` | `'vertical' \| 'horizontal'` | No | `--` | Label and field layout: vertical (label above) or horizontal (label on leading side). Prefer vertical; use horizontal when space is limited. |
| `placeholder` | `unknown` | No | `--` | Placeholders for empty start and end, shown with a swap icon between them when the group is not focus-within. |
| `granularity` | `'day' \| 'second'` | No | `--` | Smallest date/time unit shown in the fields. Only `day` and `second` are supported. |
| `className` | `never` | No | `--` | Use `FORCE__className` instead. |
| `style` | `never` | No | `--` | Inline styles are not supported; use component props or `FORCE__className`. |
| `FORCE__className` | `string` | No | `--` | 🚨 This prop is meant to be an escape hatch. 🚨<br><br>If the desired style cannot be achieved using component props, use this as a last resort. The inner workings of Capra components are implementation details and this escape hatch gives one access to those implementation details. We cannot make any guarantees that styles will applied correctly across version updates. Please use it responsibly.<br><br>Add a CSS class to the component. |
| `canClear` | `boolean` | No | `--` | When true, shows a clear control to the left of the calendar button while the field has a value. |
| `disabled` | `boolean` | No | `--` | Disables the field. |
| `id` | `string` | No | `--` | Optional id for the root; associates the label and field. |
| `readOnly` | `boolean` | No | `--` | Read-only field. |
| `required` | `boolean` | No | `--` | Required field. |
| `isInvalid` | `boolean` | No | `--` | Invalid value; `appearance="danger"` also forces an invalid state for display. |

## Props reference

### Field layout and presentation

| Prop               | Type                                 | Description                                                                                            |
| ------------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| `label`            | `string`                             | Visible label text; pair with `required` or assistive naming when the visible label is not sufficient. |
| `helperText`       | `string`                             | Descriptive or error text below the field (rendered in the description slot).                          |
| `layout`           | `'vertical' \| 'horizontal'`         | Label placement relative to the control.                                                               |
| `appearance`       | `'default' \| 'danger' \| 'warning'` | Visual status; `danger` also marks the field invalid for accessibility.                                |
| `size`             | `'sm' \| 'md'`                       | Height and density of the input shell.                                                                 |
| `leadingSlot`      | `ReactNode`                          | Optional content before the segmented inputs (same pattern as `TextInput`).                            |
| `placeholder`      | `readonly [string, string]`          | Start and end placeholders when both bounds are empty and the group is not focus-within.               |
| `id`               | `string`                             | Optional id for the root; associates the label and field.                                              |
| `FORCE__className` | `string`                             | Escape hatch: extra class on the field shell; see `StylingOverrideProps` in source.                    |
| `disabled`         | `boolean`                            | Disables the control.                                                                                  |
| `readOnly`         | `boolean`                            | Read-only mode.                                                                                        |
| `required`         | `boolean`                            | Marks the field required for forms and assistive technologies.                                         |
| `isInvalid`        | `boolean`                            | Marks the value invalid; combined with `appearance === 'danger'`.                                      |

### Value, format, overlay, and change events

| Prop                  | Type                                                      | Description                                                                               |
| --------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `value`               | `RangeValue<T> \| null`                                   | Controlled range (`T` is a `DateValue` generic, defaulting to the library `DateValue`).   |
| `defaultValue`        | `RangeValue<T> \| null`                                   | Initial range when uncontrolled.                                                          |
| `onChange`            | `(value: RangeValue<MappedDateValue<T>> \| null) => void` | Fired when the committed range changes.                                                   |
| `granularity`         | `'day' \| 'hour' \| 'minute' \| 'second'`                 | Smallest unit shown in the fields (default follows value type, e.g. day for plain dates). |
| `shouldCloseOnSelect` | `boolean \| () => boolean`                                | Whether the popover closes after a calendar interaction.                                  |

`MappedDateValue<T>` preserves time and calendar types aligned with `T` (for example `CalendarDate` vs `CalendarDateTime`).

For selecting a new range entirely inside the calendar without the overlay closing between the first and second date,
set `shouldCloseOnSelect={false}` (as in the example stories).

Use `isInvalid` and `helperText` for invalid feedback in Capra layouts. Validation behavior is fixed to ARIA-associated messaging for this shell (not configurable).

### Props not supported or intentionally fixed

| Prop                                           | Notes                                                                                        |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `children`                                     | Ignored; structure (label, inputs, calendar) is fixed.                                       |
| `style`                                        | Not part of the public styling contract; use design tokens and `FORCE__className` if needed. |
| `validationBehavior`                           | Not configurable; the implementation always uses ARIA-associated validation for this shell.  |
| `description`, `errorMessage` (slot-style API) | Not part of the public props surface; use `helperText` and validation props instead.         |