# TimeField
## Summary
`TimeField` is a [compound component](https://vega-ui.dev/docs/glossary/#compound-component) for masked time entry. It builds on `TextField` and adds format, min/max, and step constraints for time strings when the product value is time-only.
## Imports
```tsx
import {
TimeField,
TimeFieldInput,
type TimeFieldInputProps,
type TimeFieldProps,
} from '@vega-ui/react';
```
## Exported Types
- `TimeFieldProps`
- `TimeFieldInputProps`
## Minimal Composition
```tsx
import { TimeField, TimeFieldInput } from '@vega-ui/react';
export default function MinimalComposition() {
return (
);
}
```
## Required Parts
- `TimeField`: root time constraints and format provider
- `TimeFieldInput`: masked text input
## Optional Parts
- no extra public parts beyond the input
## Composition Order
1. `TimeField`
2. `TimeFieldInput`
## Variants
- Format: `HH:mm` or `HH:mm:ss`
- Bounds: optional `min` and `max`
- State: controlled or uncontrolled `value` on the root, disabled through input props
## Edge Cases
- Format, `min`, and `max` must agree with each other.
- Partial typed values should not be treated as complete times too early.
- Users need clear 24-hour format expectations in product copy.
- If the feature really stores a timestamp, `DateTimeField` is usually the clearer abstraction than splitting date and time policy ad hoc.
## Common Mistakes
- Assuming locale formatting instead of documenting the expected mask.
- Passing format-specific bounds that do not match the chosen format.
- Treating incomplete masked text as valid submission data.
## Examples
### Basic
#### Basic: daily reminder time
A labelled field for a 24-hour time. `defaultValue` on the root is an `HH:mm` string, and the helper text tells users which clock and time zone the time is in.
```tsx
import { HelperText, Label, TimeField, TimeFieldInput } from '@vega-ui/react';
export default function ReminderTime() {
return (
24-hour time in your local time zone.
);
}
```
### Controlled/Stateful
#### Controlled/Stateful: shift start and end
`value` and `onChangeValue` on the root keep both times in parent state. The start is the `min` of the end field, so an end before the start is clamped, and the shift length is computed from the two values. While a time is incomplete its value is `''`.
```tsx
import { useState } from 'react';
import { Fieldset, FieldsetLegend, Label, Text, TimeField, TimeFieldInput } from '@vega-ui/react';
const toMinutes = (time: string) => {
const [hours, minutes] = time.split(':').map(Number);
return hours * 60 + minutes;
};
const describeShift = (start: string, end: string) => {
if (!start || !end) return 'Enter both times';
const length = toMinutes(end) - toMinutes(start);
return `${Math.floor(length / 60)} h ${length % 60} min`;
};
export default function ShiftHours() {
const [start, setStart] = useState('09:00');
const [end, setEnd] = useState('17:30');
return (
);
}
```
### Form/Integration
#### Form/Integration: submitting a time
For `HH:mm` and `HH:mm:ss` the typed text already is the value, so `name` on `TimeFieldInput` submits it as is. `required` and `pattern` block an empty or incomplete time, and the reset button restores `defaultValue` of the root.
```tsx
import { FormEvent, useState } from 'react';
import { Button, HelperText, Label, Text, TimeField, TimeFieldInput } from '@vega-ui/react';
export default function QuietHoursForm() {
const [submitted, setSubmitted] = useState('');
const onSubmit = (event: FormEvent) => {
event.preventDefault();
const data = new FormData(event.currentTarget);
setSubmitted(JSON.stringify(Object.fromEntries(data)));
};
return (
);
}
```
### Layout/Overlay
#### Layout/Overlay: opening hours table
Small fields inside table cells, one row per weekday. Each input has no visible label of its own, so it gets an `aria-label` that names the day and the column.
```tsx
import {
Table,
TableBody,
TableData,
TableHead,
TableHeading,
TableRow,
TimeField,
TimeFieldInput,
} from '@vega-ui/react';
const DAYS = [
{ day: 'Monday', opens: '09:00', closes: '18:00' },
{ day: 'Tuesday', opens: '09:00', closes: '18:00' },
{ day: 'Wednesday', opens: '09:00', closes: '20:00' },
{ day: 'Thursday', opens: '09:00', closes: '18:00' },
{ day: 'Friday', opens: '10:00', closes: '16:00' },
];
export default function OpeningHoursTable() {
return (
);
}
```
### Error
#### Error: time outside an overnight window
`min` and `max` cannot describe a window that crosses midnight, so the field has no bounds and the submit handler checks the 22:00–06:00 rule itself. `error` and `aria-invalid` mark the field, and the next change of the value clears the error.
```tsx
import { FormEvent, useState } from 'react';
import { Button, HelperText, Label, TimeField, TimeFieldInput } from '@vega-ui/react';
const isOvernight = (time: string) => time >= '22:00' || time <= '06:00';
export default function NightDeliveryForm() {
const [time, setTime] = useState('');
const [error, setError] = useState('');
const invalid = error !== '';
const onChangeValue = (value: string) => {
setTime(value);
setError('');
};
const onSubmit = (event: FormEvent) => {
event.preventDefault();
if (time && !isOvernight(time)) {
setError('Night deliveries arrive between 22:00 and 06:00.');
}
};
return (
);
}
```
### Disabled
#### Disabled: read-only schedule slot
`readOnly` on `TimeFieldInput` keeps the time focusable and submitted with the form while users cannot edit it.
```tsx
import { HelperText, Label, TimeField, TimeFieldInput } from '@vega-ui/react';
export default function ReadOnlyScheduleSlot() {
return (
Set by your administrator.
);
}
```
#### Disabled: disabled by a fieldset
`TimeField` has no `disabled` prop of its own: disable the input, or a surrounding `