Integrate a custom input
A custom text component needs to participate in Conform validation and submission.
Conform · Const
controlled inputs
useInputControl connects controlled or custom React inputs to Conform by exposing their current value and helpers that simulate native input events.
How it works
Use useInputControl when a custom or controlled input must integrate with Conform. Read the current value from the returned control and call its event helpers so Conform receives browser-like updates without requiring direct native input handling.
Syntax
const control = useInputControl(metaOrOptions);Parameters
| Name | Type | Description |
|---|---|---|
metaOrOptions | Field metadata | options object | Field metadata or an options object containing key, name, formId, and initialValue. |
Returns
An input control object exposing the current value and helpers for simulating browser events.
Key points
useInputControlis a React hook for dispatching browser-like events from a controlled or custom input.- Initialize it with field metadata or options containing the field key, name, form ID, and initial value.
- Read
control.valueas the current input value when rendering a controlled component. - Use
control.change(value)to update the value and emit the events Conform expects. - Use
control.blur()to report that the logical input lost focus. - Use
control.focus()to simulate focus-related events programmatically.
Common mistakes
- A controlled input managed with
useInputControlresets its value when the field key changes. - Calling
blur()orfocus()simulates events but does not move the browser's actual keyboard focus. - Custom inputs may not receive Conform's automatic focus on submission failure; forward focus to the actual element when needed.
Example: Controlled input with useInputControl
const control = useInputControl(meta);
return (
<input
name={meta.name}
value={control.value ?? ''}
onChange={(event) => control.change(event.target.value)}
onBlur={() => control.blur()}
/>
);Connects a controlled input to Conform by reading its value and forwarding change and blur events.
When to use it
Synchronize controlled state
A React component owns its value state but must notify Conform of updates.
Simulate browser events
An application needs to trigger input, blur, or focus behavior programmatically.
Interview questions
QWhy use useInputControl for a controlled input?
useInputControl provides a control object for integrating custom inputs with Conform. Its value can drive the controlled component, while change(value) emits both change and input events.
Follow-up: How would you notify Conform that interaction ended? Call control.blur(), which simulates blur and focusout without moving real keyboard focus.
QWhat can be passed to useInputControl?
Pass field metadata or an options object containing key, name, formId, and initialValue to useInputControl. The hook then returns an input-control object with the current value and event helpers.
Follow-up: What field identity matters when resetting? The field key is used to coordinate remounting and can cause the controlled value to reset when it changes.
QHow should focus be handled with custom inputs?
The hook simulates browser events, but its focus helpers do not actually move keyboard focus. For a custom input, listen for focus and call the desired element's native focus() method when real focus delegation is required.
Follow-up: Why can automatic invalid-field focusing fail? Conform may not know which custom element should receive focus, so the component must forward focus explicitly.
Related
useControlgetInputPropsgetFormPropsfield metadata