Skip to main content

Date Picker

A locale-aware date input with an optional floating calendar, mask input, and native date form value.

Package@g4rcez/componentsSectionForm Controls

Examples

Basic Date Picker

Renders a masked text input with a calendar dropdown trigger. Submits a hidden ISO date value.

Basic
tsx
"use client";
import { DatePicker } from "@g4rcez/components";

function BasicDatePicker() {
  return (
    <DatePicker
      name="birth-date"
      title="Birth date"
      placeholder="Select a date"
      required
    />
  );
}

Controlled Value

Pass date and onChange to control the selected date externally.

Controlled
tsx
"use client";
import { useState } from "react";
import { DatePicker } from "@g4rcez/components";

function ControlledDatePicker() {
  const [date, setDate] = useState<Date | undefined>(undefined);
  return (
    <div className="flex flex-col gap-2">
      <DatePicker
        name="event-date"
        title="Event date"
        date={date}
        onChange={setDate}
        clickToClose
        required
      />
      {date && (
        <p className="text-sm text-secondary">
          Selected: {date.toLocaleDateString()}
        </p>
      )}
    </div>
  );
}

Date Range Picker

Pass range to render editable endpoint inputs and a calendar header that uses labelRange, with presets, staged selection, and Apply/Cancel actions.

Range
Report period
null
tsx
"use client";
import { useState } from "react";
import { DatePicker, type DateRangeValue } from "@g4rcez/components";

function RangeDatePicker() {
  const [range, setRange] = useState<DateRangeValue | null>(null);

  return (
    <DatePicker
      name="report-period"
      title="Report period"
      type="range"
      range={range}
      onChange={setRange}
      labelRange={{ from: "Start date", to: "End date" }}
    />
  );
}

Localized Range Picker

Override rangeLabels for non-English preset-list, action, and Today labels.

Localized
Período
tsx
"use client";
import { DatePicker } from "@g4rcez/components";

function LocalizedDatePicker() {
  return (
    <DatePicker
      name="periodo"
      title="Período"
      type="range"
      range={{}}
      rangeLabels={{
        searchPlaceholder: "Atalhos de período",
        today: "Hoje",
        cancel: "Cancelar",
        apply: "Aplicar",
      }}
    />
  );
}

Custom Presets

Provide rangePresets to replace the default menu with product-specific date shortcuts.

Custom presets
Analytics window
tsx
"use client";
import { useState } from "react";
import { DatePicker, type DateRangeValue } from "@g4rcez/components";

const subDays = (date: Date, days: number) => {
  const next = new Date(date);
  next.setDate(next.getDate() - days);
  return next;
};

function CustomPresetDatePicker() {
  const [range, setRange] = useState<DateRangeValue | null>(null);

  return (
    <DatePicker
      name="analytics-window"
      title="Analytics window"
      type="range"
      range={range}
      onChange={setRange}
      rangePresets={[
        { label: "Last 14 days", range: (today) => ({ from: subDays(today, 13), to: today }) },
        { label: "Last 90 days", range: (today) => ({ from: subDays(today, 89), to: today }) },
        { label: "Launch week", range: { from: new Date(2026, 6, 1), to: new Date(2026, 6, 7) } },
      ]}
    />
  );
}

Inline Calendar

Set floating=false to render the calendar inline instead of in a dropdown.

Inline
SunMonTueWedThuFriSat
tsx
"use client";
import { DatePicker } from "@g4rcez/components";

function InlineDatePicker() {
  return (
    <DatePicker
      name="check-in"
      title="Check-in date"
      floating={false}
      required
    />
  );
}

When to use Date Picker

Use when

You need the documented Date Picker interaction or presentation in a product workflow.

Avoid when

A native HTML element already provides the Date Picker behavior you need.

Accessibility

Keep the Date Picker labeled and use its documented keyboard interaction. The component preserves visible focus and communicates state without relying on color alone.

  • Keep keyboard focus visible and follow the documented key commands.
  • Provide an accessible name and connect descriptions or errors to the control.