Date Picker

A date picker component that implements the Horizon Design System (HDS) Date Picker patterns. Supports single date selection or date range selection with calendar popup.

<terra-date-picker></terra-date-picker>

import TerraDatePicker from '@nasa-terra/components/dist/react/date-picker';

const App = () => <TerraDatePicker />;

Usage

The Date Picker component implements the Horizon Design System (HDS) Date Picker patterns. It is a form field that includes a calendar popup, which is used to select a single date. The component uses the terra-input component for the input field.

The date picker is useful for forms involving scheduling (for example, requesting a speaker for an event on a specific day). It allows users to type a date like a normal text field, or open the calendar popup, which helps format the date correctly.

Use help text to display the desired date formatting, in case visitors choose to type their date into the field.

<!-- Single date picker -->
<terra-date-picker
  id="my-date-picker"
  label="Event Date"
  start-date="2024-03-20"
  min-date="2024-01-01"
  max-date="2024-12-31"
  help-text="Format: YYYY-MM-DD"
></terra-date-picker>

<!-- Date range picker -->
<terra-date-picker
  id="my-range-picker"
  label="Date Range"
  range
  start-date="2024-03-20"
  end-date="2024-03-25"
  min-date="2024-01-01"
  max-date="2024-12-31"
></terra-date-picker>

Properties

Events

The component emits:

• terra-date-range-change: Fired when a selection is made or changed
  • Event detail: { startDate: string, endDate: string }
    • If enable-time is off, values are YYYY-MM-DD
    • If enable-time is on, values are ISO strings (e.g., 2024-03-20T10:00:00.000Z)

Examples

Basic Usage

<terra-date-picker
  id="basic-picker"
  start-date="2024-03-20"
></terra-date-picker>

Date Range

<terra-date-picker
  id="range-picker"
  range
  start-date="2024-03-20"
  end-date="2024-03-25"
></terra-date-picker>

With Time Selection

<terra-date-picker
  id="range-time-picker"
  range
  enable-time
  start-date="2024-03-20T10:00:00Z"
  end-date="2024-03-25T15:30:00Z"
></terra-date-picker>

Custom Display Format

<terra-date-picker
  id="custom-format-picker"
  start-date="2024-03-20"
  display-format="YYYY/MM/DD"
></terra-date-picker>

Labels and Help Text

<terra-date-picker
  id="labeled-picker"
  label="Acquisition Date"
  help-text="Format: YYYY-MM-DD"
  start-date="2024-06-01"
></terra-date-picker>

<!-- Visually hide the label but keep it accessible -->
<terra-date-picker
  id="hidden-label-picker"
  label="Acquisition Date"
  hide-label
  help-text="Format: YYYY-MM-DD"
  start-date="2024-06-01"
></terra-date-picker>

Preset Ranges Sidebar

<!-- Default presets provided when show-presets is enabled -->
<terra-date-picker
  id="preset-picker"
  range
  show-presets
></terra-date-picker>

Note: Presets are shown if any part of the preset range overlaps the min-date/max-date window. When a preset is selected, dates are clamped to the allowed range. If no presets overlap, the sidebar is hidden.

Min/Max Constraints

<terra-date-picker
  id="bounded-picker"
  range
  min-date="2024-01-01"
  max-date="2024-12-31"
></terra-date-picker>

Presets With Min/Max

<terra-date-picker
  id="preset-bounded-picker"
  range
  show-presets
  min-date="2024-03-15"
  max-date="2024-03-20"
></terra-date-picker>

Only presets whose start and end are within the bounds are shown. If none qualify, the sidebar is hidden.

Split Inputs

When using range mode, you can optionally display two separate inputs side by side instead of a single combined input. This is useful when you want clearer visual separation between the start and end dates.

<!-- Range picker with split inputs -->
<terra-date-picker
  id="split-inputs-picker"
  range
  split-inputs
  start-date="2024-03-20"
  end-date="2024-03-25"
></terra-date-picker>

<!-- Split inputs with inline calendar -->
<terra-date-picker
  id="split-inline-picker"
  range
  split-inputs
  inline
  start-date="2024-03-20"
  end-date="2024-03-25"
></terra-date-picker>

Note: The split-inputs prop only has an effect when range is true. When enabled, the labels will automatically append ”(Start)” and ”(End)” to the provided label, or use “Start Date” and “End Date” if no label is provided. You can customize the labels using the start-label and end-label properties.

<!-- Custom labels for split inputs -->
<terra-date-picker
  id="custom-labels-picker"
  range
  split-inputs
  start-label="From"
  end-label="To"
  start-date="2024-03-20"
  end-date="2024-03-25"
></terra-date-picker>

Inline Mode

When inline is enabled, the calendar is always visible and displayed as part of the page flow rather than as a popover dropdown. The input field remains visible and displays the selected date(s), but clicking it does not toggle the calendar visibility since it’s always shown.

<!-- Inline single date picker -->
<terra-date-picker
  id="inline-picker"
  inline
  start-date="2024-03-20"
></terra-date-picker>

<!-- Inline date range picker -->
<terra-date-picker
  id="inline-range-picker"
  inline
  range
  start-date="2024-03-20"
  end-date="2024-03-25"
></terra-date-picker>

<!-- Inline with presets -->
<terra-date-picker
  id="inline-preset-picker"
  inline
  range
  show-presets
></terra-date-picker>

Best Practices

1. Always provide a label for accessibility - the component uses terra-input which requires proper labeling
2. Use help-text to display the desired date formatting (e.g., “Format: YYYY-MM-DD”) in case visitors choose to type their date into the field
3. Always provide an id for accessibility and to ensure unique identification
4. Use minDate and maxDate to prevent selection of invalid dates
5. Use displayFormat to match the expected input display in your application
6. Use enableTime only when time selection is necessary
7. Show showPresets to accelerate common range selections when helpful
8. Use inline mode when you want the calendar to be permanently visible as part of the page layout

Accessibility

The date picker is built with accessibility in mind:

• Keyboard navigation support
• ARIA attributes for screen readers
• Focus management
• Clear visual indicators for selected date

[component-metadata:terra-date-picker]

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

<script type="module" src="https://cdn.jsdelivr.net/npm/@nasa-terra/components@0.0.138/cdn/components/date-picker/date-picker.js"></script>

import 'https://cdn.jsdelivr.net/npm/@nasa-terra/components@0.0.138/cdn/components/date-picker/date-picker.js';

import '@nasa-terra/components/dist/components/date-picker/date-picker.js';

import TerraDatePicker from '@nasa-terra/components/dist/react/date-picker';

Slots

Learn more about using slots.

Events

Learn more about events.

Custom Properties

Learn more about customizing CSS custom properties.

Parts

Learn more about customizing CSS parts.

Dependencies

This component automatically imports the following dependencies.

• <terra-button>
• <terra-dropdown>
• <terra-icon>
• <terra-input>
• <terra-popup>