DatePicker

A single-field date control: a Button trigger that opens a Calendar inside a Popover. The trigger shows the selected date (formatted MMM dd, yyyy) or a placeholder, and the popover closes as soon as a day is picked.

DatePicker is a ready-made composition — you don’t wire up the parts yourself. Drive it as a controlled input with value and onChange; the value is a plain Date (or undefined when nothing is chosen). It selects one date only — for a two-ended range, drive a Calendar in mode="range" directly.

Basic

Pass value and onChange to control the selection. onChange fires with the chosen Date (or undefined if the day is toggled off), and the popover closes on select.

Ship date

Shipping on Tuesday, Oct 20, 2026

import { DatePicker } from "@vesyl/ui-next";
import { useState } from "react";

export default function DatePickerBasic() {
  const [shipDate, setShipDate] = useState<Date | undefined>(new Date());

  return (
    <div className="flex w-full max-w-xs flex-col gap-3">
      <label className="text-sm font-medium" htmlFor="ship-date">
        Ship date
      </label>
      <DatePicker value={shipDate} onChange={setShipDate} />
      <p className="text-sm text-muted-foreground">
        {shipDate
          ? `Shipping on ${shipDate.toLocaleDateString("en-US", {
              weekday: "long",
              month: "short",
              day: "2-digit",
              year: "numeric",
            })}`
          : "No ship date selected"}
      </p>
    </div>
  );
}

Placeholder

Start with value={undefined} for an empty field. The trigger renders placeholder (“Pick a date” by default) in muted text until a date is selected.

Requested delivery date

Leave empty to ship at the carrier's standard pace.

import { DatePicker } from "@vesyl/ui-next";
import { useState } from "react";

export default function DatePickerPlaceholder() {
  const [deliverBy, setDeliverBy] = useState<Date | undefined>(undefined);

  return (
    <div className="flex w-full max-w-xs flex-col gap-3">
      <label className="text-sm font-medium" htmlFor="deliver-by">
        Requested delivery date
      </label>
      <DatePicker
        value={deliverBy}
        onChange={setDeliverBy}
        placeholder="Select a delivery date"
      />
      <p className="text-sm text-muted-foreground">
        Leave empty to ship at the carrier&apos;s standard pace.
      </p>
    </div>
  );
}

Disabled dates and disabled control

disabledDates takes a react-day-picker Matcher (or array of matchers) and blocks those days from selection — { before: today } is the common “no past dates” guard for a pickup or ship date. Separately, disabled locks the entire control so the popover never opens.

Carrier pickup date

Past dates are not selectable.

Billing close date

The whole control is locked while the billing period is finalizing.

import { DatePicker } from "@vesyl/ui-next";
import { useState } from "react";

export default function DatePickerDisabledDates() {
  const [pickupDate, setPickupDate] = useState<Date | undefined>(undefined);

  // Pickups can't be scheduled in the past — disable every day before today.
  const today = new Date();
  today.setHours(0, 0, 0, 0);

  return (
    <div className="flex w-full max-w-xs flex-col gap-6">
      <div className="flex flex-col gap-3">
        <label className="text-sm font-medium" htmlFor="pickup-date">
          Carrier pickup date
        </label>
        <DatePicker
          value={pickupDate}
          onChange={setPickupDate}
          placeholder="Schedule a pickup"
          disabledDates={{ before: today }}
        />
        <p className="text-sm text-muted-foreground">
          {pickupDate
            ? `Pickup scheduled for ${pickupDate.toLocaleDateString("en-US", {
                month: "short",
                day: "2-digit",
                year: "numeric",
              })}`
            : "Past dates are not selectable."}
        </p>
      </div>

      <div className="flex flex-col gap-3">
        <label className="text-sm font-medium text-muted-foreground" htmlFor="locked">
          Billing close date
        </label>
        <DatePicker
          value={new Date(2026, 5, 30)}
          placeholder="Pick a date"
          disabled
        />
        <p className="text-sm text-muted-foreground">
          The whole control is locked while the billing period is finalizing.
        </p>
      </div>
    </div>
  );
}

Reference

DatePicker

A Button trigger wrapping a single-mode Calendar in a Popover. Renders the selected date as MMM dd, yyyy.

Prop	Type	Default	Description
`value`	`Date \| undefined`	—	The selected date (controlled)
`onChange`	`(date: Date \| undefined) => void`	—	Fires when a day is picked or cleared
`onBlur`	`() => void`	—	Fires when the popover closes; useful for marking a form field as touched
`placeholder`	`string`	`"Pick a date"`	Trigger text shown when no date is selected
`disabledDates`	`Matcher \| Matcher[]`	—	react-day-picker matcher for non-selectable days, e.g. `{ before: today }`
`captionLayout`	`"label" \| "dropdown" \| "dropdown-months" \| "dropdown-years"`	`"label"`	Month/year header; `dropdown` jumps years without paging. See Calendar.
`startMonth`	`Date`	—	First month in dropdown navigation (used with `captionLayout="dropdown"`)
`endMonth`	`Date`	—	Last month in dropdown navigation (used with `captionLayout="dropdown"`)
`disabled`	`boolean`	`false`	Disables the trigger so the calendar can’t open
`className`	`string`	—	Merged onto the trigger `Button`