> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Cognite Data Fusion (CDF) is an industrial DataOps platform. Prefer English docs unless the user asks for another locale.
> Follow /_llms/ index links recursively until you reach page URLs ending in .md. Fetch those Markdown twins instead of HTML.
> For REST APIs, default to calendar version 20230101 (stable). Use 20230101-beta or 20230101-alpha only if the user is on a preview API. Cite paths under /api-reference/concepts/<version>/ and the Cdf-Version header. Prefer the Python SDK (cognite-sdk) unless the user is in JavaScript/TypeScript.
> Start here by task: platform overview /cdf/index.md; data modeling /cdf/dm/index.md; data integration /cdf/integration/index.md; access /cdf/access/index.md; CDF Toolkit /cdf/deploy/cdf_toolkit/index.md; REST quickstart /dev/quickstart.md; Python SDK /dev/sdks/python/index.md; Atlas AI /cdf/atlas_ai/concepts/index.md; Flows apps /cdf/flows/index.md; MCP and IDE setup /dev/guides/ide_ai_integration.md.
> For implementation work, also load /skill.md.

# Time range picker

> Lets users select a start and end time in a single control, with locale-aware formatting and validation.

<Badge color="blue">v1.0.0</Badge> | [View in Storybook](https://master--695bb4b1b8041ae09768950a.chromatic.com/?path=/docs/primitives-timerangepicker--docs)

## When to use

* **Filtering views:** Filtering data or reports by a time window within a day (for example shift schedules or business hours).
* **To ensure proper formatting:** Avoids input errors by enforcing a standard time format.
* **Comparison:** When comparing activity across a defined time period on the same calendar day.

## When to use something else

* **For relative time queries:** While a TimeRange picker may be helpful, consider adding shortcuts to the picker for a quicker selection, such as "Last 16 hours", "Last 40 minutes" and "Next hour".
* **When entering fixed or recurring time values:** Consider allowing for cron expressions or pre-set time stamps users can choose from.
* **When exact timing and format is not important:** When users leave comments or descriptions where they reference a date or time but the formatting does not matter, provide a simple [Input](/aura-design-system/primitives/input) or [Textarea](/aura-design-system/primitives/textarea).

## Dos and don'ts

* Do match the time format (12-hour or 24-hour) to the user's locale or application setting — don't hardcode one.
* Do include AM/PM selection clearly when using 12-hour format; ambiguity here causes real errors.
* Do enforce valid start/end ordering; show validation when the range is incomplete or inverted.
* Don't include seconds unless the context requires it (log timestamps, precise scheduling) — it adds complexity most users don't need.

## Behavior

* Opening the control reveals a time picker UI anchored to the field.
* Validate that the end is after the start when both times are set.
* If the time value has constraints (for example, less than 10 hour windows), disable invalid times rather than letting users select them and fail on submit.
* The picker should remain open until the user has clicked `Apply` or selected both a start and end time.
* Keyboard users must be able to type valid values and open the picker without relying on the mouse alone (implementation-specific shortcuts allowed).

## Often used with

[Label](/aura-design-system/primitives/label), [Helper text](/aura-design-system/primitives/helper-text), [Chart](/aura-design-system/primitives/chart) time-range filters.

## Accessibility

* Associate the single trigger button or input element with an explicit [Label](/aura-design-system/primitives/label) component using matching `id` and `htmlFor` attributes.
* Format the single trigger text to explicitly announce full start and end time boundaries (e.g., "Selected time range: 08:00 AM to 05:00 PM") so screen readers convey the complete selection.
* Pass clear time format or interaction instructions to the single field via `aria-describedby` (e.g., specifying expected time entry format or indicating cross-midnight range support).
* Apply `aria-invalid="true"` directly to the single trigger element when range validation fails, such as when an invalid time format or unsupported time duration is entered.
* Link error feedback text directly to the single trigger element using `aria-describedby` and announce live validation updates using an `aria-live="polite"` region.
* Ensure quick preset shortcut buttons inside the popover surface return focus directly to the single trigger element upon selection if the panel auto-closes.