Future Export: the useControl hook

[edmundhung]

import { useControl } from '@conform-to/react/future';

The useControl hook is an experimental API released under the future export. It's designed to address the limitations of useInputControl, which works well for simple cases — but gets in the way for dynamic or custom UI components.

useInputControl automatically renders a hidden input for you, which makes it feel familiar to developers coming from traditional form libraries. But this abstraction has trade-offs:

• It encourages thinking in terms of a field instead of an input, which makes handling checkbox or radio groups awkward.
• It renders an input even when the field is conditionally hidden, which can be problematic in dynamic UIs.
• It takes control away from the developer when working directly with the DOM.

useControl is a successor to the previously undocumented unstable_useControl hook. It gives you full control over how the base input is rendered and connected to Conform. You render the input, register it manually, and decide how and when to sync its state — while still benefiting from validation, metadata, and native event handling.

The UI Libraries Integration Guide has also been updated with practical tips and examples for working with useControl. For more details on the API itself, see the useControl API reference.

What's changed

Manual input registration with full control

Unlike useInputControl, useControl doesn't render an input for you — you render and register the input manually. This gives you full control and avoids the limitations of automatic rendering.

You are required to manage the base input, but the useControl hook helps simplify the setup — more so than unstable_useControl did:

• Default value setup: Pass defaultValue (or defaultChecked) to useControl, and it will apply it when the input is first registered. If you're rendering your form server-side, you should still set the default value directly on the input if you care about the initial value before JavaScript loads.
• Focus delegation support: Just mark your input as hidden. If you want to delegate focus to a custom input component, set an onFocus handler in the options. Conform will automatically apply the necessary accessibility attributes, including aria-hidden, tabIndex={-1}, and style rules to make the hidden input focusable but invisible to screen readers.

function Input() {
  const control = useControl({
    defaultValue: '[email protected]',
    onFocus: () => customInputRef.current?.focus(),
  });

  return (
    <>
      <input
        name={fields.email.name}
        ref={control.register}
        hidden
      />
      <CustomInput
        value={control.value}
        onChange={(value) => control.change(value)}
        onBlur={() => control.blur()}
      />
    </>
  );
}

New field metadata for default values

To simplify integration, each field now includes default-related metadata:

• defaultValue for text input, single radio button or single select
• defaultOptions for multi-select or checkbox groups
• defaultChecked for single checkbox

These values are computed automatically from your form's defaultValue:

const { fields } = useForm({
  defaultValue: {
    username: 'edmundhung',
    tags: ['react', 'forms'],
    subscribe: true,
  },
});

fields.username.defaultValue;      // 'edmundhung'
fields.tags.defaultOptions;        // ['react', 'forms']
fields.subscribe.defaultChecked;   // true

They make it easier to pass the correct values when initializing useControl.

Refined control value

useControl exposes a set of properties for working with various input types:

control.value

Current value of the base input. Undefined if the registered input is a multi-select, file input, or checkbox group.

function MyInput() {
  const control = useControl({
    defaultValue: fields.username.defaultValue,
  });

  return (
    <>
      <input
        type="text"
        name={fields.username.name}
        ref={control.register}
        hidden
      />
      <CustomInput
        ref={customInputRef}
        value={control.value}
        onChange={(value) => control.change(value)}
        onBlur={() => control.blur()}
      />
    </>
  );
}

control.options

Selected options of the base input. Defined only when the registered input is a multi-select or checkbox group.

function MyMultiSelect() {
  const control = useControl({
    defaultValue: fields.tags.defaultOptions,
  });

  return (
    <>
      <select multiple name={fields.tags.name} ref={control.register} hidden />
      <CustomMultiSelect
        value={control.options}
        onChange={values => control.change(values)}
        onBlur={() => control.blur()}
      />
    </>
  );
}

control.checked

Checked state of the base input. Defined only when the registered input is a single checkbox or radio input.

function MyCheckbox() {
  const control = useControl({
    defaultChecked: fields.subscribe.defaultValue === 'yes',
    value: 'yes', // Omit it if you treat the value as a boolean
  });

  return (
    <>
      <input
        type="checkbox"
        name={fields.subscribe.name}
        ref={control.register}
        hidden
      />
      <CustomCheckbox
        checked={control.checked}
        value="yes"
        onCheck={checked => control.change(checked)}
        onBlur={() => control.blur()}
      />
    </>
  );
}

control.files

Selected files of the base input. Defined only when the registered input is a file input.

// e.g. React Aria's FileTrigger
export function FileTrigger({ label, defaultValue, description, isInvalid, errors, children, ...props }: FileTriggerProps) {
  const id = useId();
  const buttonRef = useRef<HTMLButtonElement>(null);
  const control = useControl({
    defaultValue,
    onFocus() {
      buttonRef.current?.focus();
    },
  });

  return (
    <>
      <input type="file" name={props.name} ref={control.register} hidden />
      <AriaFileTrigger
        {...props}
        onSelect={(files) => control.change(files ?? [])}
      >
        <Label>{label}</Label>
        <Button ref={buttonRef} onBlur={() => control.blur()}>
          {children}
        </Button>
        {control.files && (
          <ul>
            {control.files.map((file, i) => (
              <li key={i}>
                {file.name} ({file.size} bytes)
              </li>
            ))}
          </ul>
        )}
      </AriaFileTrigger>
    </>
  );
}

Group registration for checkbox or radio

You can register multiple checkbox or radio inputs as a group by passing an array of elements to register(). This is useful when the setup renders a set of native inputs that you want to re-use without re-implementing the group logic:

export function CheckboxGroup({ label, name, description, defaultValue, errors, children, ...props }: CheckboxGroupProps) {
  const control = useControl({ defaultValue });

  return (
    <AriaCheckboxGroup
      {...props}
      ref={wrapper => control.register(wrapper?.querySelectorAll('input'))}
      name={name}
      value={control.options ?? []}
      onChange={value => control.change(value)}
      onBlur={() => control.blur()}
    >
      {label && <Label>{label}</Label>}
      {children}
      {description && <Text slot="description">{description}</Text>}
      <FieldError>{errors}</FieldError>
    </AriaCheckboxGroup>
  );
}

If you don't need to re-use the existing native inputs, you can always represent the group with a single hidden multi-select or text input.

For complete examples, see the checkbox and radio group implementations in the React Aria example.

Examples

We've prepared examples for integrating with popular UI libraries, including a new example with React Aria components:

• React Aria Components
• Shadcn UI
• Radix UI
• Chakra UI
• Headless UI
• Material UI

If the library you're using isn't listed or you run into issues, open a discussion — we're happy to help. Contributions are also welcome if you'd like to share an example.

[PhilDL]

Hi, thank you or the amazing library and all the work you do! In our project we were already using unstable_useControl because I saw it in some of your old react-aria examples.
I thought this new future useControl would be the "unstable one" in a more public version. But it seems they are 2 different implementations.

I know I probably shouldn't have relied on the unstable API 😅 in the first place but I liked this API a lot. What is the plan for unstable_useControl, would you recommend to simply switch imports to the @conform-to/react/future ?

[edmundhung]

I should have stabilized unstable_useControl long ago. It is solid and there is nothing wrong with using it.

The new useControl hook in @conform-to/react/future is an improved version of the unstable one, built on the same core idea, and I expect migration to be relatively straightforward. Have you run into any issues moving over or noticed anything you do not like about the new version? Let me know, and I am happy to troubleshoot them with you.

Once we have gathered enough feedback on the future API, we will deprecate unstable_useControl and make the future export the default in v2.

[PhilDL]

Thanks for the clarification, I moved some components to the new API with no problem for now. My ui components have a meta: FieldMetadata<type> prop, that I was directly passing to the unstable_useControl.

The future useControl signature is still compatible with meta (no preference here, I like this new version also), so for most of my components it is just a change of import, I was handling the hidden part on my own with tailwind className="sr-only" and tabIndex={-1}.

If i want to use the hidden prop so conform handles visibility for me, it is sometimes more involved and I need to tweak my components a little bit more. Most of my components were using a text input hidden like that

<input
        {...getInputProps(meta, { type: "text" })}
        className="sr-only"
        ref={control.register}
        aria-hidden
        tabIndex={-1}
        onFocus={() => {
          actualComponentRef.current?.focus();
        }}
      />

So with the new version I have to:

• Use the correct input type and get value accordingly
• set the id, name, form props explicitely from the metadata.
• remove the tabIndex, class, aria-hidden and instead set the hidden property

Overall it's okay but a little bit of migration work.

[edmundhung]

The future useControl signature is still compatible with meta (no preference here, I like this new version also), so for most of my components it is just a change of import

I would recommend avoiding useControl(meta) going forward. It may work in many cases, but it breaks multi-select support. You need to call it like this instead:

const control = useControl({
  defaultValue: meta.defaultOptions,
  // …other settings
});

Otherwise you will only ever get the first selected value.

set the id, name, form props explicitely from the metadata.

In most cases you don't need to set id or form attribute:

• id: only required when you want to associate a <label> via htmlFor.
• form: only necessary if your input is rendered outside of its <form> element.

This is also why I no longer recommend using getInputProps: it can lead to over-specifying attributes. While handling props manually takes a bit more boilerplate, it ensures you only apply exactly what's needed.

Let me know if that clears things up or if you hit any other migration bumps. I'm happy to help! :)

[PhilDL]

Oh thank you, yes everything is clear and I will apply all your recommendations. I don't mind more boilerplate and that will make the behavior more explicit for newcomers on my project, thank you!

[andrew-shpak]

Is useControl and useField support auto convention schema on to true ?
Also I was trying to change defaultChecked by control.change(true) and value by some reason still false/default. As a workaround I switched to defaultValue. Would be awesome if examples with such behavior exists?

[edmundhung]

You can find an example from the Checkbox component in https://github.com/edmundhung/conform/tree/main/examples/react-aria. Our CI runs tests against this example so I am pretty sure it is working.

My guess is that you are using a UI library that overrides the value of the input. It is on by default, but sometimes UI library might accidentally set it to undefined and React has a bug that will make it "" (empty string), so it fails. Setting it explicitly to on might helps.

If that doesn't help, can you share a reproduction? or at least the UI library and the component you are using so I can understand better.

[andrew-shpak]

I am using heroui(wrapper around react-aria). Issues what I see on my side:

• control.register does not convert true -> "on"
• on submit value - "", but I am using stringbool instead of boolean from zod

  const control = useControl({
        defaultChecked: field.defaultChecked,
    });
    return (
        <>
            <input type="hidden" name={name}
                   ref={control.register}/>
            <Checkbox
                isSelected={control.checked}
                onValueChange={(value) => {
                    onChange?.(value);
                    onValueChange?.(value);
                    control.change?.(value);
                }}
                color={color}
                isDisabled={disabled}
                isRequired={field.required}
                data-testid={name}
            >
                {label}
            </Checkbox>
        </>
    );

[edmundhung]

I think the issue here is that your base input is not a checkbox. If you switch it to <input type="checkbox" hidden name={name} ref={control.register}/>, it should work.

I can see why this wasn't easy to catch. I should make it either boolean works with a text input, or at least show some sort of warning.

[andrew-shpak]

I think there is 1 more issue with control.change it does not accept set or map as a values so as a workaround you should convert into array

[andrew-shpak]

I tried to use select from react-aria example ( https://github.com/edmundhung/conform/blob/main/examples/react-aria/src/components/Select.tsx) and it returns onValidate the last value only.

 <>
            <select name={name} ref={control.register} hidden>
                <option />
            </select>
            <Select
                selectedKeys={control.options}
                onSelectionChange={(keys) => {
                    const selection = keys as Set<string>;
                    control.change(Array.from(selection));
                }}
                description={description}
                isDisabled={disabled}
                isRequired={field.required}
                errorMessage={errorMessage}
                isInvalid={isInvalid}
                variant="bordered"
                listboxProps={{
                    emptyContent: "Нічого не знайдено",
                }}
                label={label}
                placeholder={placeholder}
                selectionMode="multiple"
            >
                {options.map((option) => (
                    <SelectItem key={option.value} textValue={option.label}>
                        {option.label}
                    </SelectItem>
                ))}
            </Select>
        </>

[edmundhung]

You need to configure the base select element with a multiple attribute:

<select name={name} ref={control.register} multiple hidden />