# TimeField Guides

## Patterns

### Reminder Time

When to use:

- users schedule a reminder or notification time

Composition notes:

- keep the label explicit about what the time controls
- use helper text if the timezone context matters

Trade-offs:

- compact and clear
- requires explicit format expectations

```tsx
import { HelperText, Label, TimeField, TimeFieldInput } from '@vega-ui/react';

export default function ReminderTime() {
  return (
    <div style={{ display: 'grid', gap: 'var(--spacing-3)', width: '100%', maxWidth: 260 }}>
      <Label htmlFor='daily-reminder'>Daily reminder</Label>
      <TimeField defaultValue='08:30'>
        <TimeFieldInput id='daily-reminder' placeholder='hh:mm' aria-describedby='daily-reminder-hint' />
      </TimeField>
      <HelperText id='daily-reminder-hint'>24-hour time in your local time zone.</HelperText>
    </div>
  );
}
```

### Seconds-Precision Rule

When to use:

- scheduling logic or automation requires seconds

Composition notes:

- switch `format` to `HH:mm:ss`
- keep bounds in the same shape

Trade-offs:

- precise
- more cognitively demanding than minute-level entry

```tsx
import { useState } from 'react';
import { Label, Text, TimeField, TimeFieldInput } from '@vega-ui/react';

export default function SecondsPrecisionRule() {
  const [runAt, setRunAt] = useState('00:00:30');

  return (
    <div style={{ display: 'grid', gap: 'var(--spacing-8)', width: '100%', maxWidth: 260 }}>
      <div style={{ display: 'grid', gap: 'var(--spacing-3)' }}>
        <Label htmlFor='cron-time'>Run the export at</Label>
        <TimeField format='HH:mm:ss' min='00:00:30' max='23:59:30' value={runAt} onChangeValue={setRunAt}>
          <TimeFieldInput id='cron-time' placeholder='hh:mm:ss' />
        </TimeField>
      </div>
      <Text size={2} style={{ color: 'var(--label-secondary)' }}>
        Value: {runAt ? <code>{runAt}</code> : 'no complete time'}
      </Text>
    </div>
  );
}
```

### Bound Time Window

When to use:

- only a subset of the day is valid

Composition notes:

- set `min` and `max`
- explain the allowed window in nearby copy if it is not obvious

Trade-offs:

- prevents invalid entry early
- users need clear feedback when bounds reject values

```tsx
import { useState } from 'react';
import { HelperText, Label, Text, TimeField, TimeFieldInput } from '@vega-ui/react';

export default function BoundTimeWindow() {
  const [callback, setCallback] = useState('');

  return (
    <div style={{ display: 'grid', gap: 'var(--spacing-8)', width: '100%', maxWidth: 260 }}>
      <div style={{ display: 'grid', gap: 'var(--spacing-3)' }}>
        <Label htmlFor='callback-time'>Call me back at</Label>
        <TimeField min='09:00' max='18:00' value={callback} onChangeValue={setCallback}>
          <TimeFieldInput id='callback-time' placeholder='hh:mm' aria-describedby='callback-time-hint' />
        </TimeField>
        <HelperText id='callback-time-hint'>Support works 09:00–18:00. Try 07:15 or 19:40.</HelperText>
      </div>
      <Text size={2} style={{ color: 'var(--label-secondary)' }}>
        Value: {callback ? <code>{callback}</code> : 'no complete time'}
      </Text>
    </div>
  );
}
```

## Comparison

### Quick Decision Rule

Use `TimeField` when users enter a time without picking a date. Use `DateTimeField` when both date and time belong to one value.

### `TimeField` vs `TextField`

Use `TimeField` when:

- masked time entry with format and bounds matters

Use `TextField` when:

- the value is free-form text even if it contains digits or separators

### `TimeField` vs `DateTimeField`

Use `TimeField` when:

- the stored value is time-only

Use `DateTimeField` when:

- the time is inseparable from a date

### Choose This Component When

- the user should enter only a time
- mask-driven input is useful
- the business value is not a full timestamp

### Do Not Choose This Component When

- the value is a full date-time
- the text is not actually a time

## Troubleshooting

### The Field Accepts A Format Different From Product Expectations

#### Symptom

Users type a time, but the accepted pattern does not match the UI or backend expectations.

#### Likely Cause

The chosen `format` does not match the integration contract.

#### How To Verify

- inspect the `format`, `min`, and `max` props
- compare them with the expected submission format

#### Fix

Set one explicit format and keep all bounds and placeholders aligned with it.

### A Time That Looks Valid Is Still Rejected

#### Symptom

The user enters a valid-looking time string, but the form still rejects it.

#### Likely Cause

`min` or `max` constraints exclude the value.

#### How To Verify

- compare the typed value with the configured bounds

#### Fix

Adjust bounds or clarify the allowed time window in visible helper copy.

### Partial Values Are Being Treated As Final

#### Symptom

The app reacts to incomplete input like `1_` or `12:` as if it were a complete time.

#### Likely Cause

Parent logic validates too early.

#### How To Verify

- watch how state changes while typing each segment

#### Fix

Delay final validation until the input contains a complete time value.