DatePicker

View in Storybook

Explore interactive examples and all component variations in our Storybook.

The DatePicker component combines a button trigger with a calendar popover for intuitive date selection. It provides a clean, accessible interface for picking dates in forms and applications.

Basic Usage

With Pre-selected Date

Selected: 1/22/2026

Custom Placeholder

Button Variants

Outline (default)

Default

Ghost

Disabled State

Form Example

Event Start Date

Event End Date

With Preset Dates

Custom Width

Properties

DatePicker

Property	Type	Default	Description
date	Date | undefined	undefined	The selected date.
onDateChange	(date: Date | undefined) => void	undefined	Callback fired when the date changes.
placeholder	string	"Pick a date"	Placeholder text when no date is selected.
disabled	boolean	false	Whether the date picker is disabled.
className	string	undefined	Additional CSS classes for the button.
language	"enUS" | "ptBR"	"enUS"	Language for date formatting in the calendar.
buttonVariant	"default" | "outline" | "ghost" | "link" | "destructive" | "secondary"	"outline"	Button style variant.

Features

Accessibility

• Full keyboard navigation support
• ARIA attributes for screen readers
• Focus management between button and calendar
• Proper labeling and descriptions

User Experience

• Click outside to close popover
• Escape key to dismiss
• Visual feedback for selected dates
• Smooth animations

Customization

• Multiple button variants
• Custom placeholder text
• Flexible width with className
• Language support

Common Use Cases

The DatePicker component is perfect for:

• Form inputs - Date selection in registration or booking forms
• Event scheduling - Choose dates for appointments or meetings
• Deadline setting - Set due dates for tasks or projects
• Birthday selection - User profile date inputs
• Date range start/end - First step in range selection
• Availability selection - Choose available dates for services
• Filtering - Date-based filtering in data tables

Best Practices

1. Clear labels - Always provide a descriptive label for the date picker
2. Validation - Validate selected dates (e.g., end date after start date)
3. Feedback - Show selected date clearly in the button
4. Accessibility - Ensure keyboard navigation works properly
5. Mobile friendly - Test on touch devices for usability
6. Error handling - Handle invalid dates gracefully
7. Localization - Use appropriate language for your users
8. Default values - Consider pre-selecting sensible defaults

Keyboard Navigation

• Tab - Navigate to the date picker button
• Enter/Space - Open the calendar popover
• Escape - Close the popover
• Arrow keys - Navigate dates within the calendar (when open)
• Enter/Space - Select the focused date (when calendar is open)

Integration with Forms

The DatePicker works seamlessly with form libraries:

// React Hook Form example
import { DatePicker } from "buildgrid-ui";
import { Controller, useForm } from "react-hook-form";

function MyForm() {
  const { control, handleSubmit } = useForm();

  const onSubmit = (data) => {
    console.log(data);
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <Controller
        name="eventDate"
        control={control}
        render={({ field }) => (
          <DatePicker
            date={field.value}
            onDateChange={field.onChange}
            placeholder="Select event date"
          />
        )}
      />
      <button type="submit">Submit</button>
    </form>
  );
}

Related Components

• Calendar - The underlying calendar component
• Popover - The popover container used by DatePicker
• Button - The trigger button component
• Input - Alternative for manual date entry

Tips

• Use date-fns or similar libraries for date manipulation
• Consider time zones when working with dates
• Validate date ranges on both client and server
• Provide clear error messages for invalid selections
• Test with different locales and date formats
• Consider adding a "Clear" button for optional dates