Time Range Field

Allows users to input a range of times within a designated field.

llms.txt
Hotel dates 
	<script lang="ts">
  import { TimeRangeField } from "bits-ui";
</script>
 
<TimeRangeField.Root class="group flex w-full max-w-[320px] flex-col gap-1.5">
  <TimeRangeField.Label class="block select-none text-sm font-medium">
    Hotel dates
  </TimeRangeField.Label>
  <div
    class="h-input rounded-input border-border-input bg-background text-foreground focus-within:border-border-input-hover focus-within:shadow-date-field-focus hover:border-border-input-hover group-data-invalid:border-destructive flex w-full select-none items-center border px-2 py-3 text-sm tracking-[0.01em]"
  >
    {#each ["start", "end"] as const as type (type)}
      <TimeRangeField.Input {type}>
        {#snippet children({ segments })}
          {#each segments as { part, value }, i (part + i)}
            <div class="inline-block select-none">
              {#if part === "literal"}
                <TimeRangeField.Segment
                  {part}
                  class="text-muted-foreground p-1"
                >
                  {value}
                </TimeRangeField.Segment>
              {:else}
                <TimeRangeField.Segment
                  {part}
                  class="rounded-5px hover:bg-muted focus:bg-muted focus:text-foreground aria-[valuetext=Empty]:text-muted-foreground focus-visible:ring-0! focus-visible:ring-offset-0! px-1 py-1"
                >
                  {value}
                </TimeRangeField.Segment>
              {/if}
            </div>
          {/each}
        {/snippet}
      </TimeRangeField.Input>
      {#if type === "start"}
        <div aria-hidden="true" class="text-muted-foreground pl-1 pr-2">to</div>
      {/if}
    {/each}
  </div>
</TimeRangeField.Root>

Overview

The TimeRangeField component combines two Time Field components to create a time range field. Check out the Time Field component documentation for information on how to customize this component.

Structure

	<script lang="ts">
	import { TimeRangeField } from "bits-ui";
</script>
 
<TimeRangeField.Root>
	<TimeRangeField.Label>Working Hours</TimeRangeField.Label>
	{#each ["start", "end"] as const as type}
		<TimeRangeField.Input {type}>
			{#snippet children({ segments })}
				{#each segments as { part, value }}
					<TimeRangeField.Segment {part}>
						{value}
					</TimeRangeField.Segment>
				{/each}
			{/snippet}
		</TimeRangeField.Input>
	{/each}
</TimeRangeField.Root>

Managing Placeholder State

This section covers how to manage the placeholder state of the component.

Two-Way Binding

Use bind:placeholder for simple, automatic state synchronization:

	<script lang="ts">
	import { TimeRangeField } from "bits-ui";
	import { Time } from "@internationalized/date";
	let myPlaceholder = $state(new Time(12, 30));
</script>
 
<TimeRangeField.Root bind:placeholder={myPlaceholder}>
	<!-- ... -->
</TimeRangeField.Root>

Fully Controlled

Use a Function Binding for complete control over the state's reads and writes.

	<script lang="ts">
	import { TimeRangeField, type TimeValue } from "bits-ui";
	import { Time } from "@internationalized/date";
	let myPlaceholder = $state(new Time(12, 30));
 
	function getPlaceholder() {
		return myPlaceholder;
	}
 
	function setPlaceholder(newPlaceholder: TimeValue) {
		myPlaceholder = newPlaceholder;
	}
</script>
 
<TimeRangeField.Root bind:placeholder={getPlaceholder, setPlaceholder}>
	<!-- ... -->
</TimeRangeField.Root>

Managing Value State

This section covers how to manage the value state of the component.

Two-Way Binding

Use bind:value for simple, automatic state synchronization:

	<script lang="ts">
	import { TimeRangeField, type TimeRange } from "bits-ui";
	import { Time } from "@internationalized/date";
	let myValue = $state<TimeRange>({
		start: new Time(12, 30),
		end: new Time(12, 30),
	});
</script>
 
<button
	onclick={() => {
		myValue = {
			start: myValue.start.add({ hours: 1 }),
			end: myValue.end.add({ hours: 1 }),
		};
	}}
>
	Add 1 hour
</button>
<TimeRangeField.Root bind:value={myValue}>
	<!-- ... -->
</TimeRangeField.Root>

Fully Controlled

Use a Function Binding for complete control over the state's reads and writes.

	<script lang="ts">
	import { TimeRangeField, type TimeRange } from "bits-ui";
 
	let myValue = $state<TimeRange | undefined>({
		start: undefined,
		end: undefined,
	});
 
	function getValue() {
		return myValue;
	}
 
	function setValue(newValue: TimeRange | undefined) {
		myValue = newValue;
	}
</script>
 
<DateRangeField.Root bind:value={getValue, setValue}>
	<!-- ... -->
</DateRangeField.Root>

API Reference

TimeRangeField.Root

The root time field component.

Property Type Description
value $bindable
TimeRange

The selected time range.

Default: undefined
onValueChange
function

A function that is called when the selected time range changes.

Default: undefined
placeholder $bindable
TimeValue

The placeholder time, which is used to determine what time to start the segments from when no value exists.

Default: undefined
onPlaceholderChange
function

A function that is called when the placeholder time changes.

Default: undefined
errorMessageId
string

The id of the element which contains the error messages for the field when the time is invalid.

Default: undefined
validate
function

A function that returns whether or not a time is unavailable.

Default: undefined
onInvalid
function

A callback fired when the field's value is invalid.

Default: undefined
minValue
TimeValue

The minimum valid time that can be entered.

Default: undefined
maxValue
TimeValue

The maximum valid time that can be entered.

Default: undefined
granularity
enum

The granularity to use for formatting the field. The field will render segments for each part of the time up to and including the specified granularity.

Default: minute
hideTimeZone
boolean

Whether or not to hide the time zone segment of the field. This only applies when using a ZonedDateTime as the value prop.

Default: false
hourCycle
enum

The hour cycle to use for formatting times. Defaults to the locale preference

Default: undefined
locale
string

The locale to use for formatting times.

Default: 'en-US'
disabled
boolean

Whether or not the field is disabled.

Default: false
readonly
boolean

Whether or not the field is readonly.

Default: false
readonlySegments
EditableTimeSegmentPart[]

An array of segments that should be readonly, which prevent user input on them.

Default: undefined
required
boolean

Whether or not the field is required.

Default: false
onStartValueChange
function

A function that is called when the start time changes.

Default: undefined
onEndValueChange
function

A function that is called when the end time changes.

Default: undefined
ref $bindable
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See Child Snippet docs for more information.

Default: undefined
Data Attribute Value Description
data-time-range-field-root
''

Present on the root element.

TimeRangeField.Input

The container for the segments of the time field.

Property Type Description
type required
enum

The type of field to render (start or end).

Default: undefined
name
string

The name of the time field used for form submission. If provided, a hidden input element will be rendered alongside the time field.

Default: undefined
ref $bindable
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See Child Snippet docs for more information.

Default: undefined
Data Attribute Value Description
data-invalid
''

Present on the element when the field is invalid.

data-disabled
''

Present on the element when the field is disabled.

data-time-field-input
''

Present on the element.

TimeRangeField.Segment

A segment of the time field.

Property Type Description
part required
TimeSegmentPart

The part of the time to render.

Default: undefined
ref $bindable
HTMLSpanElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See Child Snippet docs for more information.

Default: undefined
Data Attribute Value Description
data-invalid
''

Present on the element when the field is invalid

data-disabled
''

Present on the element when the field is disabled

data-segment
enum

The type of segment the element represents.

data-time-field-segment
''

Present on the element.

TimeRangeField.Label

The label for the time field.

Property Type Description
ref $bindable
HTMLSpanElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See Child Snippet docs for more information.

Default: undefined
Data Attribute Value Description
data-invalid
''

Present on the element when the field is invalid

data-time-field-label
''

Present on the element.