Date Field

PreviousNext

A form input for selecting dates with calendar picker, validation, and automatic range correction.

'use client';

import { DateField } from '@/ui/forms/DateField';

export function DateFieldDemo() {
  return (
    <DateField
      label="Select a date"
      description="Choose your preferred date"
      openDatepicker="Open date picker"
    />
  );
}

Installation

npx shadcn@latest add https://develop.trident-ui.pro.clubmed/r/date-field.json

Usage

'use client';
 
import { useState } from 'react';
import { DateField } from '@/docs/lib/ui/forms/date-field';
 
export function Component() {
  const [date, setDate] = useState<Date | null>(null);
 
  return (
    <DateField
      label="Departure Date"
      description="Select your preferred departure date"
      openDatepicker="Open calendar picker"
      value={date}
      onChange={(name, value) => setDate(value)}
      min={new Date()}
      required
    />
  );
}

API Reference

DateField

PropTypeDefaultDescription
labelstringundefinedThe label text displayed above the input field.
descriptionstringundefinedHelper text displayed below the label to provide additional context.
openDatepickerstringundefinedAccessibility text for the calendar button, announced to screen readers. Should describe the action, e.g., "Open calendar picker".
idstringAuto-generatedThe unique identifier for the input field. Auto-generated if not provided.
namestringSame as idThe name attribute for the input field, used in form submissions. Defaults to the id value.
valueDate | nullundefinedThe current date value. Pass null or undefined for no selection.
onChange(name: string, value: Date) => voidundefinedCallback function called when the date changes. Receives the field name and the new Date value.
minDateundefinedThe minimum allowed date. Dates below this will auto-correct on blur.
maxDateundefinedThe maximum allowed date. Dates above this will auto-correct on blur.
iconIconicNames"CalendarDefault"The icon name from @clubmed/trident-icons to display in the calendar button.
iconTypeIconicTypesundefinedOptional icon type variant for the calendar icon.
disabledbooleanfalseWhether the field is disabled. Disabled fields have reduced opacity and cannot be interacted with.
requiredbooleanfalseWhether the field is required. Displays a red asterisk next to the label.
hideRequiredStarbooleanfalseWhen true, hides the required asterisk even if the field is required.
validationStatus"default" | "error" | "success""default"The validation state of the field. Changes border color and shows status icons.
errorMessagestringundefinedError message text displayed when validationStatus is "error".
dataTestIdstring"DateField"Custom test ID for the component wrapper, useful for testing.
classNamestringundefinedAdditional CSS classes for the input element.

The component also accepts all standard HTML input attributes via spreading (...rest).

Notes

Date Picker Integration

The component uses the native HTML5 date input with enhanced styling. Clicking the calendar icon button triggers the browser's native date picker via the showPicker() API.

Automatic Range Correction

When min and/or max props are provided, the component automatically corrects out-of-range dates when the input loses focus (blur event). The correction behavior:

  • If only min is set: corrects to min if value is below
  • If only max is set: corrects to max if value is above
  • If both are set: corrects to the closest boundary date
  • No correction occurs while the input is focused, allowing users to type freely

Validation States

The component supports three validation states via the validationStatus prop:

  • "default": Normal state with light gray border
  • "error": Red border with cross icon, displays errorMessage if provided
  • "success": Green border with check icon

Form Control Integration

DateField wraps the input in a FormControl component that provides consistent styling for labels, descriptions, error messages, and validation states across all form fields.

Accessibility

  • The calendar button includes a screen reader label via openDatepicker prop
  • The component automatically associates the label with the input using the id attribute
  • Disabled fields have appropriate visual feedback with reduced opacity
  • Required fields are indicated with a red asterisk (unless hideRequiredStar is true)
  • Status icons (check/cross) provide visual validation feedback

Client Component

This component uses React hooks (useState, useEffect, useRef) and must be used in a client component. Add "use client" at the top of files that use this component.

Date Format

The component internally uses ISO 8601 date format (YYYY-MM-DD) for the native input. The value and onChange props work with JavaScript Date objects for easier integration with your application logic.