Skip to main contentSkip to site searchSkip to component search
Honeycomb

use-duration-formatter

Since: ver.10.0.0 Implements predefined formats for Duration internationalization.

Props

Prop nameTypeDefaultDescription
display"short" | "narrow" | "long" | "digital" | undefinedshort

The duration display format.

localeLocalesArgument

The locale for number formatting. Used for `Intl.NumberFormat` API.

intlFormatOptionsNumberFormatOptions | undefined

Options forwarded to each individual part of the `Intl.NumberFormat` API. Intl.NumberFormat

For most cases we advise you to use the provided Duration formatter component as it also handles the semantic and accessible markup of duration objects.

If you need to customize the markup, you can use the useDurationFormatter hook, which mimics the basic functionalities of the (currently unstable) Intl.DurationFormat API.

Format

The format function returns a formatted string of the provided duration object based on user-defined localization.

If you wish to override user locale, you can use the locale parameter.

import { useDurationFormatter, FormRow, Select, SelectOption, Text } from '@flixbus/honeycomb-react';

const [locale, setLocale] = React.useState();

const Duration = ({ display, hours, minutes, seconds }) => {
  const formatter = useDurationFormatter({ locale, display });

  return <time>{formatter.format({ hours, minutes, seconds })}</time>;
};

<div>
  <FormRow>
    <Select aria-label="Locale" id="locale-picker" value={locale} onChange={(event) => { setLocale(event.target.value || undefined) }}>
      <SelectOption value="">User preference</SelectOption>
      <SelectOption value="en-US">en-US</SelectOption>
      <SelectOption value="de-DE">de-DE</SelectOption>
      <SelectOption value="fr-FR">fr-FR</SelectOption>
      <SelectOption value="pt-BR">pt-BR</SelectOption>
    </Select>
  </FormRow>
  <Text>
    <strong>narrow:</strong> <Duration display="narrow" hours={9} minutes={16} seconds={30} />
  </Text>
  <Text>
    <strong>short:</strong> <Duration display="short" hours={9} minutes={16} seconds={30} />
  </Text>
  <Text>
    <strong>long:</strong> <Duration display="long" hours={9} minutes={16} seconds={30} />
  </Text>
  <Text>
    <strong>digital:</strong> <Duration display="digital" hours={9} minutes={16} seconds={30} />
  </Text>
</div>

FormatToParts

You can call formatToParts function to get parts of the formatted string and extract only the information you need from them.

In the example bellow we add digital separator in a separate element to make it blink like a digital clock.

import { Tag, useDurationFormatter } from '@flixbus/honeycomb-react';
import { Icon, IconStopwatch } from '@flixbus/honeycomb-icons-react';

const duration = {
  hours: 9,
  minutes: 16
}

const formatter = useDurationFormatter({
  locale: 'de-DE',
  display: 'digital'
});

const durationParts = formatter.formatToParts(duration);

console.log(durationParts);

<Tag display="subtle" appearance="danger">
  <Icon InlineIcon={IconStopwatch} />
  <time dateTime={`PT${duration.hours}H${duration.minutes}M`}>
    <strong>
      {durationParts.map((part) => part.type === 'literal' && part.value === ':'
        ? <span className="digital-separator" key={part.value}>{part.value}</span>
        : part.value
      )}
    </strong>
  </time>
</Tag>