DateRangeField

Patterns

Range Field With Popover Calendar

When to use:

• Users need one connected range field in a form or filter bar.
• The range picker should open on demand.

Composition notes:

• Keep DateRangeFieldInput as the primary entry surface and label it.
• Mount DateRangeFieldCalendar inside PopoverContent; the first picked day writes the start, the second the end.

Trade-offs:

• Saves layout space.
• Requires explicit incomplete-range handling: a single date is a valid entry.

import {
  CalendarContent,
  CalendarDay,
  CalendarDays,
  CalendarHeader,
  CalendarMonth,
  CalendarMonthLabel,
  CalendarMonths,
  CalendarNextButton,
  CalendarPrevButton,
  CalendarViewButton,
  CalendarViewButtonGroup,

Range Field In Filter Drawers

When to use:

• Reporting or analytics filters live inside Drawer or Sheet.
• The range is one of several stacked filters.

Composition notes:

• Keep the field compact and explicit about range semantics.
• Test popover placement inside the parent overlay.

Trade-offs:

• Works well in dense filter UIs.
• Adds overlay coordination complexity.

import { CSSProperties, useState } from 'react';
import { XIcon } from '@vega-ui/icons';
import {
  Button,
  CalendarContent,
  CalendarDay,
  CalendarDays,
  CalendarHeader,
  CalendarMonth,
  CalendarMonthLabel,
  CalendarMonths,
  CalendarNextButton,

Range Field For Validation-Heavy Reporting Forms

When to use:

• The range is required before export or report generation.
• The product needs explicit error copy for incomplete or blocked ranges.

Composition notes:

• Use native required and a pattern for the full range; min and max are already enforced while typing, and a reversed range is swapped.
• disabledDates applies only to the calendar, so align it with backend reporting rules and repeat it on submit.

Trade-offs:

• Stronger validation clarity.
• name on the input submits the typed text; to send from and to as ISO days, mirror onChangeValue into hidden inputs as in Form/Integration.

import { FormEvent, useState } from 'react';
import {
  Button,
  CalendarContent,
  CalendarDay,
  CalendarDays,
  CalendarHeader,
  CalendarMonth,
  CalendarMonthLabel,
  CalendarMonths,
  CalendarNextButton,
  CalendarPrevButton,

Comparison

Quick Decision Rule

Use DateRangeField when one control should own both the start and end date.

DateRangeField vs DateField

Use DateRangeField when the pair of dates must stay connected and be validated together.

Use DateField when only one date is stored.

Main trade-off: DateRangeField reduces coordination mistakes, but it is heavier to label, validate, and review.

DateRangeField vs DateTimeField

Use DateRangeField when the feature is about a date span rather than a specific timestamp.

Use DateTimeField when one final scheduled moment matters more than a span.

Main trade-off: ranges communicate duration, while date-time fields communicate a precise instant.

DateRangeField vs Calendar

Use DateRangeField when the control belongs in a form and typing is important.

Use Calendar when a visible calendar-first range selection experience is the primary UI.

Main trade-off: DateRangeField is more form-friendly, while Calendar is stronger for exploration-heavy picking.

Choose This Component When

• Start and end dates belong to one business concept.
• The feature needs one label, one error state, and one filter slot.
• Users may type or pick the range.
• The range should behave like one field rather than two loosely coupled inputs.

Do Not Choose This Component When

• Only one date is needed.
• The stored value must include time.
• The UI needs a fully visible calendar-first range picker instead of a field-led control.

Troubleshooting

Only One Side Of The Range Is Saved

Symptom

The product submits a start or end date, but the other side is missing or stale.

Likely Cause

The surrounding form or state model treats the range as two unrelated values instead of one connected field.

How To Verify

• Inspect the final payload or form state.
• Confirm whether both dates are derived from the same field interaction.

Fix

Model the result as one connected range and validate incomplete state explicitly.

Calendar Trigger Opens But No Range Picker Appears

Symptom

The icon button is present, but clicking it never reveals the range calendar.

Likely Cause

DateRangeFieldTriggerIconButton was rendered without PopoverTrigger, PopoverContent, or DateRangeFieldCalendar.

How To Verify

• Check whether the trigger is inside PopoverTrigger.
• Check whether PopoverContent contains DateRangeFieldCalendar.

Fix

Compose the trigger and calendar through Popover.

Incomplete Range Is Treated As Valid

Symptom

Users can submit only a start date or only an end date when the feature requires both.

Likely Cause

Validation only checks the field shape superficially and does not enforce complete range semantics.

How To Verify

• Submit the form with one side missing.
• Compare client validation with business requirements.

Fix

Treat partial ranges as an explicit editing state and block submit until the range is complete.