TimeField

A time field allows the user to enter a time to an input.

Uncontrolled Value

By default, the TimeField component handles its value uncontrolled. In the uncontrolled variant you can pass in a defaultValue to set a value by default.

<TimeField label='Time' defaultValue={new Time(2, 35)} />

<TimeField label='Time' defaultValue={new Time(2, 35)} />

<TimeField
  label="Time"
  defaultValue={new Time(
    2,
    35
  )}
/>

Controlled Value

You can also handle the value of the component in a controlled manner. To do so, you can pass in a value prop as well as an onChange handler to modify the value when the user types.

function Example() {
  const [value, setValue] = useState(new Time(2, 35));

  return (
    <div>
      <TimeField 
        label='Time' 
        value={value} 
        onChange={setValue} 
      />

      <div>Value: {value.toString()}</div>
    </div>
  );
}

function Example() {
  const [value, setValue] = useState(new Time(2, 35));

  return (
    <div>
      <TimeField 
        label='Time' 
        value={value} 
        onChange={setValue} 
      />

      <div>Value: {value.toString()}</div>
    </div>
  );
}

function Example() {
  const [
    value,
    setValue
  ] = useState(
    new Time(2, 35)
  );

  return (
    <div>
      <TimeField
        label="Time"
        value={value}
        onChange={setValue}
      />

      <div>
        Value:{' '}
        {value
          .toString()}
      </div>
    </div>
  );
}

Granularity

The granularity of the TimeField can be modified through the granularity prop. If you add a granulatiry smaller than day it will automatically display a timefield with the timezone.

<TimeField label='Time' granularity='millisecond' />
<TimeField label='Time' granularity='second' />
<TimeField label='Time' granularity='minute' />
<TimeField label='Time' granularity='hour' />

<TimeField label='Time' granularity='millisecond' />
<TimeField label='Time' granularity='second' />
<TimeField label='Time' granularity='minute' />
<TimeField label='Time' granularity='hour' />

<TimeField
  label="Time"
  granularity="millisecond"
/>
<TimeField
  label="Time"
  granularity="second"
/>
<TimeField
  label="Time"
  granularity="minute"
/>
<TimeField
  label="Time"
  granularity="hour"
/>

Hour Cycle

The hour cycle of the TimeField can be modified through the hourCycle prop.

<TimeField label='Time' granularity='minute' hourCycle={12} />
<TimeField label='Time' granularity='minute' hourCycle={24} />

<TimeField
  label="Time"
  granularity="minute"
  hourCycle={12}
/>
<TimeField
  label="Time"
  granularity="minute"
  hourCycle={24}
/>

<TimeField
  label="Time"
  granularity="minute"
  hourCycle={12}
/>
<TimeField
  label="Time"
  granularity="minute"
  hourCycle={24}
/>

Timezone

If you add a granulatiry smaller than day it will automatically display a timefield with the timezone. You can hide the timezone through the hideTimeZone prop.

<TimeField label="Time" granularity="minute" hideTimeZone />

<TimeField label="Time" granularity="minute" hideTimeZone />

<TimeField
  label="Time"
  granularity="minute"
  hideTimeZone
/>

Labeling

A TimeField component should be labeled with a visual text through the label prop. If the TimeField does not include a textual label, an aria-label or aria-labelledby prop need to be provided to support assistive technology such as screen readers.

<TimeField label='Time' />

<TimeField label='Time' />

<TimeField label="Time" />

Label Alignment

For languages that are read left-to-right (LTR), such as English, the label of the TimeField component is displayed on the left side of the input. For right-to-left (RTL) languages, such as Arabic, this is flipped. You can control the position of the label through the labelPlacement prop.

<TimeField label='Time' labelPlacement='top end' />

<TimeField label='Time' labelPlacement='top end' />

<TimeField
  label="Time"
  labelPlacement="top end"
/>

Label Position

By default, the label of the TimeField component is displayed above the input. With the labelPlacement prop this placement can be adjusted to be on the side of the input.

<TimeField label='Time' labelPlacement='side end' />

<TimeField label='Time' labelPlacement='side end' />

<TimeField
  label="Time"
  labelPlacement="side end"
/>

Required

To indicate to the user that the TimeField is required you can use the isRequired prop.

<TimeField label='Time' isRequired />

<TimeField label='Time' isRequired />

<TimeField
  label="Time"
  isRequired
/>

Validation

The TimeField component has built-in accessible validation support. To indicate whether the field is valid or not you can use the errorMessage prop.

function Example() {
  const [value, setValue] = useState();

  const isValid = !!value;

  return (
    <TimeField 
      label='Time' 
      value={value}
      onChange={setValue} 
      errorMessage={!isValid && 'Entering a time is required.'} 
    />
  );
}

function Example() {
  const [value, setValue] = useState();

  const isValid = !!value;

  return (
    <TimeField
      label="Time"
      value={value}
      onChange={setValue}
      errorMessage={!isValid &&
        'Entering a time is required.'}
    />
  );
}

function Example() {
  const [
    value,
    setValue
  ] = useState();

  const isValid =
    !!value;

  return (
    <TimeField
      label="Time"
      value={value}
      onChange={setValue}
      errorMessage={!isValid &&
        'Entering a time is required.'}
    />
  );
}

Description

To give further instructions or more verbose examples to the user about a TimeField you can provide a description prop. Avoid using error like tone of voice of the message. If an errorMessage prop is provided it will replace the description.

<TimeField label="Time" description="Please enter a time" />

<TimeField label="Time" description="Please enter a time" />

<TimeField
  label="Time"
  description="Please enter a time"
/>

Placeholder

To give further instructions or examples to the user about a TimeField you can provide a placeholderValue prop.

<TimeField label='Time' placeholderValue={new Time(8)} />

<TimeField label='Time' placeholderValue={new Time(8)} />

<TimeField
  label="Time"
  placeholderValue={new Time(
    8
  )}
/>

Contextual Help

To offer the user contextual help, the TimeField supports passing a contextualHelp prop, that accepts a ReactNode.

<TimeField 
  label='Time' 
  contextualHelp={(
    <ContextualHelp variant="info">
      <Header>
        <Heading>Lorem Ipsum</Heading>
      </Header>
      <Content>
        <Text>
          Lorem ipsum dolor sit amet, consectetur adipiscing elit. 
        </Text>
      </Content>
    </ContextualHelp>
  )} 
/>

<TimeField
  label="Time"
  contextualHelp={
    <ContextualHelp variant="info">
      <Header>
        <Heading>Lorem Ipsum</Heading>
      </Header>
      <Content>
        <Text>
          Lorem ipsum dolor sit amet, consectetur
          adipiscing elit.
        </Text>
      </Content>
    </ContextualHelp>
  }
/>

<TimeField
  label="Time"
  contextualHelp={
    <ContextualHelp variant="info">
      <Header>
        <Heading>
          Lorem Ipsum
        </Heading>
      </Header>
      <Content>
        <Text>
          Lorem ipsum
          dolor sit
          amet,
          consectetur
          adipiscing
          elit.
        </Text>
      </Content>
    </ContextualHelp>
  }
/>

Disabled

The TimeField component can be disabled via the isDisabled prop.

<TimeField label="Time" defaultValue={new Time(2, 35)} isDisabled />

<TimeField
  label="Time"
  defaultValue={new Time(2, 35)}
  isDisabled
/>

<TimeField
  label="Time"
  defaultValue={new Time(
    2,
    35
  )}
  isDisabled
/>

Read Only

The TimeField component can be marked as read only via the isReadOnly prop.

<TimeField label="Time" defaultValue={new Time(2, 35)} isReadOnly />

<TimeField
  label="Time"
  defaultValue={new Time(2, 35)}
  isReadOnly
/>

<TimeField
  label="Time"
  defaultValue={new Time(
    2,
    35
  )}
  isReadOnly
/>

Accessibility

In order to support internationalization, provide a localized string to the label or aria-label prop.

API