# Field: Date Range (category: special)

URL: https://docs.forms.saastro.io/docs/daterange

<FieldPreview name="daterange" description="Interactive demo of date range field" />

## Overview

The date range field allows users to select a start and end date using a calendar interface. It's ideal for booking systems, date filters, and any scenario requiring a date period.

## Usage

### Basic Date Range

```tsx

const config = FormBuilder.create('booking')
  .addField('stayDates', (f) =>
    f
      .type('daterange')
      .label('Check-in / Check-out')
      .placeholder('Select dates')
      .required('Please select your stay dates'),
  )
  .addStep('main', ['stayDates'])
  .build();
```

### With Default Range

```tsx
const nextWeek = new Date();
nextWeek.setDate(nextWeek.getDate() + 7);

.addField('reportPeriod', (f) =>
  f.type('daterange')
    .label('Report Period')
    .value({ from: new Date(), to: nextWeek })
    .required()
)
```

### JSON Configuration

```json
{
  "type": "daterange",
  "label": "Check-in / Check-out",
  "placeholder": "Select dates",
  "schema": { "required": true }
}
```

## Props

| Prop          | Type                                                  | Default | Description                |
| ------------- | ----------------------------------------------------- | ------- | -------------------------- |
| `type`        | `'daterange'`                                         | -       | Field type (required)      |
| `label`       | `string`                                              | -       | Label text                 |
| `placeholder` | `string`                                              | -       | Placeholder text           |
| `helperText`  | `string`                                              | -       | Help text below field      |
| `value`       | `{ from: Date, to: Date }`                            | -       | Default date range         |
| `columns`     | `Partial<Record<Breakpoint, number>>`                 | -       | Grid columns by breakpoint |
| `disabled`    | `boolean \| function \| ConditionGroup`               | `false` | Disable the field          |
| `hidden`      | `boolean \| function \| ConditionGroup \| Responsive` | `false` | Hide the field             |

## Value Format

The date range field produces a value object:

```typescript
{
  from: Date,  // Start date
  to: Date     // End date
}
```

## Validation

### Required Range

```tsx
.addField('vacation', (f) =>
  f.type('daterange')
    .label('Vacation Period')
    .required('Please select your vacation dates')
)
```

## Use Cases

1. **Hotel booking**: Check-in / check-out dates
2. **Event scheduling**: Event start and end
3. **Report filtering**: Date range for data
4. **Leave requests**: Vacation periods

## Styling

### Custom Classes

```tsx
.addField('stayDates', (f) =>
  f.type('daterange')
    .label('Check-in / Check-out')
    .required()
    .classNames({
      wrapper: 'bg-muted/30 p-4 rounded-lg',
      input: 'border-2 border-primary/20',
      label: 'text-lg font-semibold',
      error: 'text-destructive text-sm',
    })
)
```

### Responsive Layout

```tsx
.addField('reportPeriod', (f) =>
  f.type('daterange')
    .label('Report Period')
    .columns({ default: 12, md: 8 })
)
```

### JSON Styling

```json
{
  "type": "daterange",
  "label": "Check-in / Check-out",
  "wrapper_className": "bg-muted/30 p-4 rounded-lg",
  "input_className": "border-2 border-primary/20",
  "label_className": "text-lg font-semibold",
  "columns": { "default": 12, "md": 8 }
}
```

## Related Fields

- [Date](/docs/date) - Single date selection

## Accessibility

- Built on react-day-picker
- Keyboard navigation
- Range selection feedback
- Screen reader support