# DatePicker

> Select a date from a calendar popover.

**URL:** https://inference.sh/docs/agents/widgets/date-picker
**Last updated:** 2026-09-18

---

Select a date from a calendar popover.

## Preview

```
[YYYY-MM-DD     📅▼]
```

## Usage

```go
node := models.WidgetNode{
    Type:        models.WidgetNodeTypeDatePicker,
    Name:        "birthday",
    Placeholder: "Select date",
}
```

## Props

| Name | Type | Description | Default |
|------|------|-------------|---------|
| `type` | `"date-picker"` | Node type | required |
| `name` | `string` | Form field name | required |
| `placeholder` | `string` | Placeholder text | - |
| `defaultValue` | `string` | Initial ISO date (e.g., `2024-01-31`) | - |
| `min` | `string` | Earliest selectable ISO date (inclusive) | - |
| `max` | `string` | Latest selectable ISO date (inclusive) | - |
| `disabled` | `boolean` | Disable interactions | `false` |
| `clearable` | `boolean` | Show clear button to unset value | `false` |
| `required` | `boolean` | Mark as required | `false` |
| `variant` | `string` | Visual style: `solid`, `soft`, `outline`, `ghost` | `"outline"` |
| `size` | `string` | Control size token | `"md"` |
| `pill` | `boolean` | Fully rounded pill shape | `false` |
| `block` | `boolean` | Extend to 100% width | `false` |
| `side` | `string` | Calendar position: `top`, `bottom`, `left`, `right` | - |
| `align` | `string` | Calendar alignment: `start`, `center`, `end` | `"center"` |
| `onChangeAction` | `ActionConfig` | Action dispatched on date change | - |

## Examples

### Basic DatePicker

```go
{
    Type:        models.WidgetNodeTypeDatePicker,
    Name:        "date",
    Placeholder: "Select a date",
}
```

### With Default Value

```go
{
    Type:         models.WidgetNodeTypeDatePicker,
    Name:         "start_date",
    DefaultValue: "2024-01-15",
}
```

### Date Range Constraints

```go
{
    Type:        models.WidgetNodeTypeDatePicker,
    Name:        "booking_date",
    Placeholder: "Choose date",
    Min:         "2024-01-01",
    Max:         "2024-12-31",
}
```

### With Label

```go
{
    Type: models.WidgetNodeTypeCol,
    Gap:  1,
    Children: []models.WidgetNode{
        {Type: models.WidgetNodeTypeLabel, Value: "Date of Birth", FieldName: "dob"},
        {
            Type:        models.WidgetNodeTypeDatePicker,
            Name:        "dob",
            Placeholder: "YYYY-MM-DD",
            Max:         "2010-01-01", // Must be at least 14 years old
            Clearable:   true,
        },
    },
}
```

### Booking Form

```go
widget := &models.Widget{
    Type:        models.WidgetTypeUI,
    Title:       "Book Appointment",
    Interactive: true,
    Children: []models.WidgetNode{
        {
            Type: models.WidgetNodeTypeCol,
            Gap:  3,
            Children: []models.WidgetNode{
                {Type: models.WidgetNodeTypeDatePicker, Name: "date", Placeholder: "Select date", Required: true},
                {Type: models.WidgetNodeTypeSelect, Name: "time", Placeholder: "Select time", Options: []models.WidgetSelectOption{
                    {Label: "9:00 AM", Value: "09:00"},
                    {Label: "10:00 AM", Value: "10:00"},
                    {Label: "11:00 AM", Value: "11:00"},
                }},
            },
        },
    },
    Actions: []models.WidgetActionButton{
        {Label: "Book", Action: models.WidgetAction{Type: "book_appointment"}},
    },
}
```

## Form Data

The selected date is included as an ISO date string:

```json
{
  "date": "2024-06-15",
  "dob": "1990-05-20"
}
```

## TypeScript

```typescript
const node: WidgetNode = {
  type: "date-picker",
  name: "date",
  placeholder: "Select date",
  min: "2024-01-01",
  max: "2024-12-31",
}
```

## Best Practices

1. **Use ISO format** - Always `YYYY-MM-DD` for dates
2. **Set reasonable constraints** - Use `min`/`max` to prevent invalid selections
3. **Provide placeholder** - Guide users on expected format
4. **Consider timezone** - Dates are date-only, not datetime