@neo4j-ndl/react/skills/ndl-react/components/date-picker.md

React implementation of Neo4j Design System

# DatePicker

Import: `import { DatePicker } from '@neo4j-ndl/react'`

## Props

### DatePicker

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `isClearable` | `boolean` |  | `false` | Whether to show the clear button. |
| `isDisabled` | `boolean` |  |  | Whether the date picker is disabled. |
| `reactDatePickerProps` | `DatePickerProps` | ✅ |  | Props forwarded to underlying `react-datepicker` component. |
| `ref` | `Ref<HTMLDivElement>` |  |  | A ref to apply to the root element. |
| `textInputProps` | `(TextInputProps & BaseProps<"input">)` |  |  | Props for the embedded `TextInput` component. |
| `timePickerProps` | `TimePickerProps` |  |  | Props for the embedded `TimePicker` component. |
| `timeZonePickerProps` | `(TimeZonePickerProps & BaseProps<"input">)` |  |  | Props for the embedded `TimeZonePicker` component. |

The `reactDatePickerProps` prop is forwarded to the underlying `react-datepicker` component. See the [react-datepicker documentation](https://reactdatepicker.com/) for more information.

Where `TextInputProps` is defined in the `TextInput` component and `TimePickerProps` is defined in the `TimePicker` component.

## Accessibility

## Implementation guidelines

You must provide an `aria-label` or label via the `textInputProps` prop to the underlying input element for accessibility. Use the `htmlAttributes` prop in the `textInputProps` prop to add additional attributes to the input element, not the `htmlAttributes` prop on the root level of the DatePicker component.

## Examples

### Default

```tsx
import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';

import { DatePicker } from '@neo4j-ndl/react';
import { useState } from 'react';

const Component = () => {
  const [selectedDate, setSelectedDate] = useState<Date | null>(
    new Date('2023-05-27'),
  );
  const handleOnChange = (date: Date | null) => {
    setSelectedDate(date);
  };

  return (
    <DatePicker
      reactDatePickerProps={{
        onChange: handleOnChange,
        popperProps: {
          strategy: 'fixed',
        },
        selected: selectedDate,
      }}
      textInputProps={{
        htmlAttributes: {
          'aria-label': 'Date picker input',
        },
      }}
    />
  );
};

export default Component;
```

### Clearable

```tsx
import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';

import { DatePicker } from '@neo4j-ndl/react';
import { useState } from 'react';

export const Component = () => {
  const [selectedDate, setSelectedDate] = useState<Date | null>(
    new Date('2023-05-27'),
  );

  const handleOnChange = (date: Date | null) => {
    setSelectedDate(date);
  };

  return (
    <DatePicker
      isClearable
      reactDatePickerProps={{
        onChange: handleOnChange,
        popperProps: {
          strategy: 'fixed',
        },
        selected: selectedDate,
      }}
      textInputProps={{
        htmlAttributes: {
          'aria-label': 'Clearable date picker input',
        },
      }}
    />
  );
};

export default Component;
```

### Disabled

```tsx
import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';

import { DatePicker } from '@neo4j-ndl/react';
import { useState } from 'react';

const Component = () => {
  const [selectedDate, setSelectedDate] = useState<Date | null>(
    new Date('2023-05-27'),
  );
  const handleOnChange = (date: Date | null) => {
    setSelectedDate(date);
  };

  return (
    <DatePicker
      isDisabled={true}
      reactDatePickerProps={{
        onChange: handleOnChange,
        selected: selectedDate,
      }}
      textInputProps={{
        htmlAttributes: {
          'aria-label': 'Date picker input',
        },
      }}
    />
  );
};

export default Component;
```

### Full

```tsx
import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';

import { DatePicker } from '@neo4j-ndl/react';
import { useState } from 'react';

const Component = () => {
  const [selectedDate, setSelectedDate] = useState<Date | null>(
    new Date('2023-05-27'),
  );
  const handleOnChange = (date: Date | null) => {
    setSelectedDate(date);
  };

  return (
    <DatePicker
      textInputProps={{
        helpText: 'With help text',
        isDisabled: false,
        isFluid: false,
        isReadOnly: false,
        isRequired: false,
        label: 'This one has a label',
        moreInformationText: 'With information icon text',
        showRequiredOrOptionalLabel: false,
      }}
      timePickerProps={{
        format: 'hh:mm aa',
        isDisabled: false,
        isFluid: false,
        isReadOnly: false,
        isRequired: false,
        timeInterval: 20,
      }}
      reactDatePickerProps={{
        onChange: handleOnChange,
        popperProps: {
          strategy: 'fixed',
        },
        selected: selectedDate,
        showTimeInput: true,
      }}
    />
  );
};

export default Component;
```

### In Dialog

```tsx
import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';

import { DatePicker, Dialog } from '@neo4j-ndl/react';
import { useState } from 'react';

const Component = () => {
  const [selectedDate, setSelectedDate] = useState<Date | null>(
    new Date('2023-05-27'),
  );
  const handleOnChange = (date: Date | null) => {
    setSelectedDate(date);
  };

  return (
    <Dialog isOpen={true} aria-label="Dialog">
      <Dialog.Header>Using Date Picker inside a dialog</Dialog.Header>
      <Dialog.Description className="n-flex n-flex-col n-gap-token-32">
        <DatePicker
          timePickerProps={{
            timeInterval: 20,
          }}
          reactDatePickerProps={{
            onChange: handleOnChange,
            selected: selectedDate,
            showTimeInput: true,
          }}
          textInputProps={{
            htmlAttributes: {
              'aria-label': 'Date picker input',
            },
          }}
        />
      </Dialog.Description>
    </Dialog>
  );
};

export default Component;
```

### Min Max Date

```tsx
import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';

import { DatePicker } from '@neo4j-ndl/react';
import { addWeeks } from 'date-fns';
import { useState } from 'react';

const Component = () => {
  const [selectedDate, setSelectedDate] = useState<Date | null>(
    new Date('1994-10-03'),
  );
  const handleOnChange = (date: Date | null) => {
    setSelectedDate(date);
  };

  return (
    <DatePicker
      reactDatePickerProps={{
        maxDate: addWeeks(new Date('1994-10-01'), 1),
        minDate: new Date('1994-10-01'),
        onChange: handleOnChange,
        openToDate: new Date('1994-10-01'),
        popperProps: {
          strategy: 'fixed',
        },
        selected: selectedDate,
      }}
      textInputProps={{
        htmlAttributes: {
          'aria-label': 'Date picker input',
        },
      }}
    />
  );
};

export default Component;
```

### Opens To Date

```tsx
import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';

import { DatePicker } from '@neo4j-ndl/react';
import { useState } from 'react';

const Component = () => {
  const [selectedDate, setSelectedDate] = useState<Date | null>(
    new Date('2023-05-27'),
  );
  const handleOnChange = (date: Date | null) => {
    setSelectedDate(date);
  };

  return (
    <DatePicker
      reactDatePickerProps={{
        highlightDates: [new Date('2010-02-01')],
        onChange: handleOnChange,
        openToDate: new Date('2010-02-01'),
        popperProps: {
          strategy: 'fixed',
        },
        selected: selectedDate,
      }}
      textInputProps={{
        htmlAttributes: {
          'aria-label': 'Date picker input',
        },
      }}
    />
  );
};

export default Component;
```

### Portaled

```tsx
import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';

import { DatePicker } from '@neo4j-ndl/react';
import { useState } from 'react';

const Component = () => {
  const [selectedDate, setSelectedDate] = useState<Date | null>(
    new Date('2023-05-27'),
  );
  const handleOnChange = (date: Date | null) => {
    setSelectedDate(date);
  };

  return (
    <div id="datepicker-portal-root">
      <DatePicker
        reactDatePickerProps={{
          onChange: handleOnChange,
          popperProps: {
            strategy: 'fixed',
          },
          portalId: 'datepicker-portal-root',
          selected: selectedDate,
        }}
        textInputProps={{
          htmlAttributes: {
            'aria-label': 'Date picker input',
          },
        }}
      />
    </div>
  );
};

export default Component;
```

### Range

```tsx
import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';

import { DatePicker } from '@neo4j-ndl/react';
import { useState } from 'react';

const Component = () => {
  const [dates, setDates] = useState<[Date | null, Date | null]>([
    new Date('2023-05-05'),
    new Date('2023-05-08'),
  ]);

  const handleOnChange = (dates: [Date | null, Date | null]) => {
    setDates(dates);
  };

  return (
    <DatePicker
      reactDatePickerProps={{
        endDate: dates[1],
        onChange: handleOnChange,
        popperProps: {
          strategy: 'fixed',
        },
        selectsRange: true,
        startDate: dates[0],
      }}
      textInputProps={{
        htmlAttributes: {
          'aria-label': 'Date picker input',
        },
      }}
    />
  );
};

export default Component;
```

### Starts On Monday

```tsx
import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';

import { DatePicker } from '@neo4j-ndl/react';
import { useState } from 'react';

const Component = () => {
  const [selectedDate, setSelectedDate] = useState<Date | null>(
    new Date('2023-05-27'),
  );
  const handleOnChange = (date: Date | null) => {
    setSelectedDate(date);
  };

  return (
    <DatePicker
      reactDatePickerProps={{
        calendarStartDay: 1,
        onChange: handleOnChange,
        popperProps: {
          strategy: 'fixed',
        },
        selected: selectedDate,
      }}
      textInputProps={{
        htmlAttributes: {
          'aria-label': 'Date picker input',
        },
      }}
    />
  );
};

export default Component;
```

### Text Input Props

```tsx
import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';

import { DatePicker } from '@neo4j-ndl/react';
import { useState } from 'react';

const Component = () => {
  const [selectedDate, setSelectedDate] = useState<Date | null>(
    new Date('2023-05-27'),
  );
  const handleOnChange = (date: Date | null) => {
    setSelectedDate(date);
  };

  return (
    <DatePicker
      textInputProps={{
        helpText: 'With help text',
        label: 'This one has a label',
      }}
      reactDatePickerProps={{
        onChange: handleOnChange,
        popperProps: {
          strategy: 'fixed',
        },
        selected: selectedDate,
      }}
    />
  );
};

export default Component;
```

### With Time Picker

```tsx
import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';

import { DatePicker } from '@neo4j-ndl/react';
import { useState } from 'react';

const Component = () => {
  const [selectedDate, setSelectedDate] = useState<Date | null>(
    new Date('2023-05-27'),
  );
  const handleOnChange = (date: Date | null) => {
    setSelectedDate(date);
  };

  return (
    <DatePicker
      timePickerProps={{
        format: 'hh:mm',
        timeInterval: 20,
      }}
      reactDatePickerProps={{
        dateFormat: 'yyyy-MM-dd hh:mm',
        onChange: handleOnChange,
        popperProps: {
          strategy: 'fixed',
        },
        selected: selectedDate,
        showTimeInput: true,
      }}
      textInputProps={{
        htmlAttributes: {
          'aria-label': 'Date picker input',
        },
      }}
    />
  );
};

export default Component;
```

### With Timezone

```tsx
import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';

import { DatePicker } from '@neo4j-ndl/react';
import { useState } from 'react';

const Component = () => {
  const [selectedDate, setSelectedDate] = useState<Date | null>(
    new Date('2023-05-27T14:30:00'),
  );
  const [selectedTimeZone, setSelectedTimeZone] = useState<string>('UTC');

  const handleOnChange = (date: Date | null) => {
    setSelectedDate(date);
  };

  const handleTimeZoneChange = (timezone: string) => {
    setSelectedTimeZone(timezone);
  };

  return (
    <div>
      <DatePicker
        timePickerProps={{
          format: 'hh:mm',
          timeInterval: 15,
        }}
        timeZonePickerProps={{
          onChange: handleTimeZoneChange,
          value: selectedTimeZone,
        }}
        reactDatePickerProps={{
          onChange: handleOnChange,
          popperProps: {
            strategy: 'fixed',
          },
          selected: selectedDate,
          showTimeInput: true,
        }}
        textInputProps={{
          htmlAttributes: {
            'aria-label': 'Date picker input',
          },
        }}
      />
      <div style={{ marginTop: '1rem' }}>
        <p>
          <strong>Selected Date:</strong>{' '}
          {selectedDate ? selectedDate.toISOString() : 'None'}
        </p>
        <p>
          <strong>Selected Timezone:</strong> {selectedTimeZone}
        </p>
      </div>
    </div>
  );
};

export default Component;
```

### With Timezone Both Mode

```tsx
import { useState } from 'react';

import { Typography } from '../../typography';
import { DatePicker } from '../DatePicker';

export const DatePickerWithTimeZoneBothMode = () => {
  const [selectedDate, setSelectedDate] = useState<Date | null>(
    // Every day is Christmas in Needle :)
    new Date('2025-12-24'),
  );
  const [selectedTimeZone, setSelectedTimeZone] =
    useState<string>('America/New_York');

  return (
    <div style={{ maxWidth: '400px', padding: '20px' }}>
      <Typography variant="title-4" style={{ marginBottom: '16px' }}>
        DatePicker with TimeZone (Both Mode)
      </Typography>
      <Typography variant="body-medium" style={{ marginBottom: '24px' }}>
        This example shows the DatePicker with the TimeZonePicker in
        &quot;both&quot; mode, displaying both UTC offsets and city-based
        timezones in separate sections.
      </Typography>

      <DatePicker
        textInputProps={{
          label: 'Select Date and Time with Timezone',
        }}
        timePickerProps={{
          format: 'hh:mm',
        }}
        timeZonePickerProps={{
          mode: 'both',
          onChange: (tz) => {
            setSelectedTimeZone(tz);
          },
          value: selectedTimeZone,
        }}
        reactDatePickerProps={{
          dateFormat: 'yyyy-MM-dd hh:mm',
          onChange: (date) => {
            setSelectedDate(date);
          },
          selected: selectedDate,
          showTimeInput: true,
        }}
      />

      <div
        style={{
          backgroundColor: 'var(--theme-color-neutral-bg-default)',
          borderRadius: '4px',
          display: 'flex',
          flexDirection: 'column',
          marginTop: '24px',
          padding: '16px',
        }}
      >
        <Typography variant="label">Selected Values:</Typography>
        <Typography variant="body-small">
          <strong>Date: </strong>
          {selectedDate?.toISOString() ?? 'None'}
        </Typography>
        <Typography variant="body-small">
          <strong>Timezone:</strong> {selectedTimeZone || 'None'}
        </Typography>
      </div>
    </div>
  );
};

export default DatePickerWithTimeZoneBothMode;
```