Axon 911 Frontend DocsAxon 911 Frontend Docs
Axon 911 Frontend Docs
    Loading navigation…
U
User
Switch to light mode
  1. Components
  3. Duration Field
  5. API and Development

Duration Field

API and Development

View SourceOpens in a new tabSubmit IssueOpens in a new tab
Import DurationField, DurationFieldLimitEdge, DurationFieldPart, DurationFieldSize, DurationUnit, durationToMilliseconds, durationToSeconds from @prepared911/ui/duration-field.
PropTypeDefaultNotes
labelLocalizedMessagerequiredNames the group. A click focuses the amount.
amountLabelLocalizedMessagerequiredAccessible name of the amount spinbutton.
unitLabelLocalizedMessagerequiredAccessible name of the unit choice.
unitsone to five { unit, label }requiredSix or more, or none, is a type error.
presetsnone to five { label, value }noneSix or more is a type error and warns once in development.
presetsLabelLocalizedMessagerequired with presetsAccessible name of the preset choice.
value, defaultValueDuration | nulluncontrolled, null{ amount, unit }; null is empty.
onValueChange(value, details) => voiddetails.part: amount, unit, preset, form. Reasons: input-change, keyboard-step, item-press, press-hold, list-navigation, form-reset. Cancelable except form-reset.
onFocusFocusEventHandler<HTMLElement>Called once when focus enters the field from outside. Not called when focus moves between the amount, its steppers, the unit and the presets.
onBlurFocusEventHandler<HTMLElement>Called once when focus leaves the whole field for somewhere outside, so a form library validates and marks the field touched once per visit.
defaultUnitDurationUnitdefault value's unit, then first unitUnit shown while empty.
min, maxDuration | Partial<Record<DurationUnit, number>>0 / unboundedOverall or per unit. The amount is never negative.
stepnumber1Distance between amounts.
descriptionLocalizedMessageUnder the controls; linked to the group.
error, invalidLocalizedMessage, booleanThe error shows while invalid.
required, requiredHintboolean, LocalizedMessageLabel marker, native required on the amount, and a hint under the label.
disabled, readOnlybooleanfalseDisabled dims every part. Read-only keeps every part focusable and ignores changes.
placeholderLocalizedMessageAmount placeholder.
decrementLabel, incrementLabelLocalizedMessageNames of the stepper buttons; a button is not rendered without its name.
valueAnnouncement(formattedAmount, unit, edge) => LocalizedMessagethe formatted amountPolite live region after a stepper press or a limit.
localestringruntime localeDigits of the amount.
name, unitName, formstringAmount and unit are posted through hidden inputs.
idstringgeneratedId of the amount input.
autoFocusbooleanFocuses the amount on mount.
sizeInputSizeLarge
className, data-*On the root.
refRef<HTMLInputElement>The amount input.
DurationUnit is Seconds, Minutes, Hours, Days or Weeks. durationToSeconds(duration) and durationToMilliseconds(duration) convert a value; milliseconds round to a whole millisecond. The surface is curated rather than a native attribute passthrough, because the host is a group of four controls and no one native element can take them.
Props
NameTypeDefaultDescription
amountLabelLocalizedMessage—Accessible name of the amount spinbutton, such as "Amount".
labelLocalizedMessage—Visible label of the whole field. It names the group, and a click on it focuses the amount.
unitLabelLocalizedMessage—Accessible name of the unit choice, such as "Unit".
unitsDurationUnitOptions—The units the user can pick, one to five, each with the label the caller supplies. Two to five render as a segmented choice; one renders as a suffix on the amount and no choice. More than five is a type error.
autoFocusboolean—Focuses the amount on mount.
classNamestring—Classes on the root. Put overrides in @layer chroma.overrides.
decrementLabelLocalizedMessage—Accessible name of the amount's decrement button. The button is not rendered without it.
defaultUnitDurationUnit—The unit shown while the value is empty. Defaults to the unit of defaultValue, then to the first of units.
defaultValueDuration | null—Initial value when uncontrolled. Also what a native form reset restores.
descriptionLocalizedMessage—Supporting copy below the controls, linked with the group's aria-describedby.
disabledboolean—Disables every part.
errorLocalizedMessage—Error copy below the controls while {@link invalid} is true.
formstring—Native form of both hidden inputs and of the amount.
idstring—Id of the amount input, which the label points at. Generated when omitted.
incrementLabelLocalizedMessage—Accessible name of the amount's increment button. The button is not rendered without it.
invalidboolean—Paints the invalid edge, sets aria-invalid and shows error.
localestring—BCP 47 locale for the digits of the amount. Defaults to the runtime locale.
maxDurationLimit—Upper bound: a {@link Duration} (overall) or an amount per unit. Unbounded when omitted.
minDurationLimit—Lower bound: a {@link Duration} (overall) or an amount per unit. The amount never goes below 0.
namestring—Native name: posts the amount (an empty string when empty).
onBlurFocusEventHandler<HTMLElement>—Called once when focus leaves the whole field for somewhere outside it, such as the next field. It is not called when focus moves between its parts, so a form library validates on blur once per visit.
onFocusFocusEventHandler<HTMLElement>—Called once when focus enters the field from outside it. It is not called when focus moves between the amount, its steppers, the unit and the presets. Use it with onBlur to track whether the field was touched.
onValueChange((value: Duration | null, details: DurationFieldChangeDetails) => void)—Called for every value change. details.part says which part changed and details.reason why. Every change is cancelable except a native form reset.
placeholderLocalizedMessage—Placeholder of the amount while it is empty.
presetsDurationPresets—No presets. Shortcuts that set the amount and the unit together. At most five; more is a type error.
presetsLabelLocalizedMessage—No presets, so nothing to name. Accessible name of the preset choice, such as "Quick picks".
readOnlyboolean—The amount reads and focuses; the unit and presets keep their selection and ignore changes.
refRef<HTMLInputElement>—Ref to the amount input.
requiredboolean—Shows the label's required marker and makes the amount required, natively and for assistive technology.
requiredHintLocalizedMessage—Form-level explanation of required fields, shown under the label.
sizeInputSize—Control scale. Defaults to {@link InputSize.Large}.
stepnumber—Distance between amounts. Defaults to 1.
unitNamestring—Native name of a second hidden input that posts the shown unit. Omit it to post the amount only.
valueDuration | null—Controlled value. null is a controlled empty value; undefined is uncontrolled.
valueAnnouncementDurationFieldValueAnnouncementCopy—Copy for the live announcement after a stepper press or a limit. Defaults to the formatted amount alone.
Storybook
Interactive examples and edge cases for this component are in Storybook.
DefaultOpens in a new tab
Previous
Duration Field / Usage
Next
Duration Field / Accessibility
On this page
Props
Storybook