DatePicker

A date, time, or datetime selection component with a calendar popover and time spinner.

Import#

import { DatePicker } from "asheeui";

Usage#

"use client";

import { DatePicker } from "asheeui";
import { useState } from "react";

export default function Basic() {
  const [selected, setSelected] = useState<Date | null>(null);

  return (
    <div className="w-full max-w-md">
      <DatePicker
        selected={selected}
        onChange={setSelected}
        label="Select Date"
      />
    </div>
  );
}

Examples#

Date selection#

Time selection#

Datetime selection#

Clearable#

Disable future dates#

Custom picker styling#

Inheritance#

DatePicker extends the <Input /> component and inherits all of its props and functionality. This means you can use any Input prop with DatePicker, including:

• size, radius, variant, color
• label, labelAlign, description, message
• status, required, isLoading, disabled
• className, and all native input attributes

What DatePicker adds#

DatePicker extends Input with the following additional features:

What DatePicker modifies#

What DatePicker does not inherit#

The following Input props are not available on DatePicker:

Props#

Picker Configuration#

The calendar popover appearance is controlled through the picker prop:

Global Configuration#

DatePicker reads defaults from four places, in this order of precedence:

1. Instance prop: set directly on <DatePicker />
2. Component config: components.datePicker in your ashee.config
3. Theme default: defaultVariant / defaultColor / defaultRadius in your ashee.config
4. Built-in fallback: component's internal default values

Component config#

// ashee.config.ts
import type { ExternalConfig } from "asheeui";

export const config: ExternalConfig = {
  components: {
    datePicker: {
      size: "md",
      radius: "md",
      variant: "bordered",
      color: "primary",
      mode: "date",
      labelAlign: "left",
      picker: {
        portal: true,
      },
    },
  },
};

Built-in fallbacks#

{
  size: "md",
  radius: "md",
  variant: "bordered",
  color: "primary",
  status: "default",
  labelAlign: "left",
  mode: "date",
}

Date Formatting#

The DatePicker automatically formats dates for display based on the selected mode:

Manual Input#

Users can type dates directly into the input field. The component will parse the input intelligently:

• Typing 15012024 in date mode → 15/01/2024
• Typing 1430 in time mode → 14:30:00
• Typing 150120241430 in datetime mode → 15/01/2024 14:30:00

The cursor position is preserved during formatting, making manual input feel natural and responsive.

Portal Behavior#

The DatePicker calendar popover is rendered in a React portal by default. This means the popover is attached to document.body rather than staying in the component's DOM hierarchy.

Why use a portal?#

• Escapes CSS containment: The popover appears above other content even when inside containers with overflow: hidden or contain: layout
• Avoids stacking context issues: The popover maintains proper z-index regardless of parent stacking contexts
• Works with any parent: The popover functions correctly regardless of where the DatePicker is placed in the component tree
• Prevents clipping: The popover is never clipped by parent containers

When to disable the portal#

You may want to disable the portal (by setting picker.portal={false}) when:

• You need the popover to stay within a specific container for testing purposes
• You are rendering inside a shadow DOM or iframe where document.body is not appropriate
• You have specific layout requirements that depend on the popover remaining in the DOM hierarchy

You can also provide a custom picker.portalTarget to render the popover into a specific container instead of document.body.

Accessibility#

• Renders a native combobox role with aria-expanded and aria-haspopup="dialog"
• Uses aria-invalid for error states
• Uses aria-disabled for disabled state
• Supports keyboard navigation with focus management
• Calendar navigation uses semantic button elements with proper ARIA labels
• Time spinners include increment/decrement buttons with aria-label
• Focus management via Floating UI with focus trapping
• Clear button includes aria-label="Clear selection"
• Month navigation buttons have aria-label="Previous month" and aria-label="Next month"
• Disabled dates are properly marked with disabled attribute

Notes#

• Modes: The component supports three modes - date (calendar only), time (time spinner only), and datetime (both calendar and time).
• Status Colors: When status is set to error, success, or warning, the input border automatically reflects the status color.
• Clearable: When isClearable is true, a clear button appears when a date is selected.
• Disable Future: When disableFuture is true, future dates are disabled in the calendar view.
• Manual Input: Users can type dates directly with smart parsing and cursor preservation.
• Time Precision: Time selection includes hours, minutes, and seconds.
• Portal: The calendar popover is portaled to document.body by default. This can be disabled via the picker.portal prop or component config.
• Inheritance: DatePicker inherits all Input props except value, defaultValue, and onChange.