Form contract / The props contract
The props contract
Twenty-three props are implemented identically by all eleven components. Learn them once.
Shared by every component
The full list is on each component page, generated from BaseFieldProps in the source rather than transcribed. The ones worth calling out:
The ones that matter
PROPTYPEWHY
onChange(value: T) => voidEmits the canonical value. No synthetic event to unwrap, no e.target.value.
onBlur() => voidFires when focus leaves the whole component — not when it moves from the country button to the number field. Otherwise react-hook-form's onBlur mode misfires constantly.
namestringLands on a hidden canonical input, so FormData and Server Actions receive T rather than the display text.
refRef<HTMLInputElement>Points at the primary input through useImperativeHandle, so shouldFocusError lands on a real field.
mode"standalone" | "managed"An escape hatch. The mode is normally detected, not configured.
showError"touched" | "change" | "blur" | "never"Defaults to "touched": silent until the first blur, then live.
messagesMessageMapOverride any built-in message by rule name, per instance or per provider.
Two modes, detected not configured
Rendered on its own, a field owns its error message. Rendered inside a form library, it goes quiet and lets the form own it. You never pass a prop to say which: the mode is inferred from whether aria-invalid or aria-describedby was supplied, or from a react-hook-form context being present.
The result is that you never get two copies of the same error, which is the usual failure mode when a component insists on rendering its own.