Skip to content

Early previewhamur is not on npm yet. The components are being built in the open, follow along on GitHub.

InputsReact

Year Field

A year typed in one segment, a real input with the spinbutton role.

Rendered by React 19.3.1

Loading React…
import { Field } from '@hamur/react/field'
import { YearField } from '@hamur/react/year-field'

export default function YearFieldExample() {
  return (
    <Field.Root name="born" className="field">
      <Field.Label>Birth year</Field.Label>
      <YearField.Root
        className="date-field"
        locale="en-US"
        today="2026-11-07"
        max="2026"
        autoComplete="bday"
      >
        <YearField.Input className="date-field-input">
          {({ segments }) =>
            segments.map((segment) => (
              <YearField.Segment
                key={segment.index}
                segment={segment}
                className="date-field-segment"
              />
            ))
          }
        </YearField.Input>
        <YearField.Clear className="date-field-clear">
          ×
        </YearField.Clear>
      </YearField.Root>
    </Field.Root>
  )
}
Not measured yetTests passing in React
17.7 KiBSize
Not measured yetMemory
Not measured yetSpeed
[N] commits

Installation

npm i @hamur/react

Not on npm yet. The package goes out under the chosen name.

Anatomy

Import the component and assemble its parts:

<YearField.Root>
  <YearField.Input>
    <YearField.Segment />
  </YearField.Input>
  <YearField.Clear />
</YearField.Root>

Examples

The demo at the top is the one example this component has so far.

API reference

25 props across 4 parts, in React syntax. className, style, render are listed once, under Shared props.

ClearYearField.Clear

Clears the whole value, including a partly typed one. It is out of the tab order: Backspace clears a segment from the keyboard. Renders a <button>.

InputYearField.Input

The visual control: it wraps the segments. Its children are a function of the segments, since their order depends on the locale; without children it renders every segment. Renders a <div>.

Input props
PropTypeDefault
childrenThe segments, or a function of them: ({ segments }) => ....React.ReactNode | ((context: { segments: FieldSegment[]; }) => React.ReactNode)—

RootYearField.Root

Groups all parts of a field that edits a year in one segment. Values are year strings such as '2026' (four digits, zero-padded below 1000). onValueChange is called only with a complete year, or null. Renders a <div>.

Root props
PropTypeDefault
onIncompleteChangeEvent handler called when the segments change while no complete value exists, with the((parts: FieldParts, eventDetails: DateFieldRootChangeEventDetails) => void)—
localeThe BCP 47 locale of the segment order, literals, digits and day periods.string'en-US'
forceLeadingZerosWhether the day, month and hour show a leading zero.boolean—
placeholderValueThe value an empty segment takes on its first Up or Down press.string—
todayThe date of today ('2026-11-07'), for the starting point of an empty date segment.`${number}-${number}-${number}`—
timeZoneThe time zone that decides what today is, when today is not given.string—
autoAdvanceWhether focus moves to the next segment when the typed number cannot get another digit.booleantrue
segmentRoleThe role of the segments.DateFieldSegmentRole'spinbutton'
labelsThe texts the field adds: the segment names, the text of an empty segment, the Clear label.Partial<DateFieldLabels>—
disabledWhether the component should ignore user interaction.booleanfalse
readOnlyWhether the user should be unable to change the value.booleanfalse
requiredWhether the user must fill in the field before submitting a form.booleanfalse
invalidWhether the field is invalid.booleanfalse
nameIdentifies the field when a form is submitted.string—
formIdentifies the form that owns the hidden input.string—
inputRefA ref to access the first segment.React.Ref<HTMLInputElement>—
valueThe year, null for none.`${number}` | null—
defaultValueThe year when initially rendered.`${number}` | null—
onValueChangeEvent handler called when the year changes: a complete year, or null when the field is((value: `${number}` | null, eventDetails: YearFieldRootChangeEventDetails) => void)—
minThe earliest valid year ('1990').`${number}` | `${number}-${number}-${number}` | `${number}-${number}`—
maxThe latest valid year.`${number}` | `${number}-${number}-${number}` | `${number}-${number}`—
isYearUnavailableWhether a year cannot be chosen.((year: `${number}`) => boolean)—
autoComplete'bday' gives the segment the bday-year autocomplete token, 'cc-exp' the cc-exp-year"off" | "cc-exp" | "bday"'off'
Root data attributes
Data attributeDescription
data-disabledPresent when the field is disabled.
data-readonlyPresent when the field does not allow changing the value.
data-requiredPresent when the field is required.
data-emptyPresent when no segment has a value.
data-filledPresent when every segment has a value.
data-incompletePresent when some segments have a value and others do not.
data-focusedPresent when focus is inside the field.
data-invalidPresent when the field is invalid.

SegmentYearField.Segment

One segment of the value. An editable segment (year, month, day, hour, minute, second, millisecond, day period) is a real <input> with the spinbutton role; a literal (/, :) is a <span> hidden from assistive technology., or a <span> for a literal. Renders an <input>.

Segment props
PropTypeDefault
segmentrequiredThe segment to render, one of the segments the Input gives its children.FieldSegment—

Shared props

Every part that renders an element takes these.

Shared props
PropType
classNameCSS class applied to the element, or a function that returns a class based on the component's state.string | ((state: State) => string | undefined)
styleStyle applied to the element, or a function that returns a style object based on the component's state.React.CSSProperties | ((state: State) => React.CSSProperties | undefined)
renderAllows you to replace the component's HTML element with a different tag, or compose it with another component.React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, State>

Keyboard and accessibility

Keyboard

Keyboard
KeysDoesPart
Types the year; four digits commit itSegment
ArrowUpArrowDownStep the year by oneSegment
TabLeaves the field and commits fewer than four digits as typedSegment
ControlVMetaVPaste a yearSegment

Accessibility

What the parts set
PartSetsSo that
Rootrole="group" named by the Field label; data-invalidthe field is announced once, "Birth year, group"
Segmentinput with role="spinbutton" named by the year field, aria-valuetext, aria-invalidthe year is read with whether it is valid
Segmentautocomplete bday-year or cc-exp-yearthe browser fills a saved birthday or card expiry

Focus order

  1. The year segment. Nothing takes focus on mount.
  2. Clear is out of the tab order. Tab leaves the field.