Unstyled Form Control

The Unstyled Form Control component is a utility that lets you associate a form input with auxiliary components, such as labels, error indicators, or helper text.

Demos Components API Hooks API

Introduction

Unstyled Form Control is a utility that wraps an input component with other associated components in order to make the state of the input available to those components.

For instance, you may want to show an additional element asking the user to enter a value if the input is empty, or display a warning icon if the entered value is incorrect.

Component

Usage

After installation, you can start building with this component using the following basic elements:

import FormControlUnstyled from '@mui/base/FormControlUnstyled';

export default function MyApp() {
  return (
    <FormControlUnstyled>
      {/* <input> and/or other contents of the form */}
    </FormControlUnstyled>
  );
}

Basics

Unstyled Form Control wraps around the elements of a form that need access to the state of an <input>. For instance, if the form's Submit button needs to change states after the user enters information, then the component will be structured like this:

<FormControlUnstyled>
  <input>
  <button>Submit</button>
</FormControlUnstyled>

The following demo shows how to create and style a form that uses Unstyled Form Control to wrap the elements of the form. Note that it also uses the useFormControlUnstyledContext hook in order to pass props to the custom Unstyled Input—see the Hook section below for more details.

Name *

<FormControlUnstyled defaultValue="" required>
  <Label>Name</Label>
  <Input />
  <HelperText />
</FormControlUnstyled>

<FormControlUnstyled defaultValue="" required>
  <Label>Name</Label>
  <Input />
  <HelperText />
</FormControlUnstyled>

Press Enter to start editing

Hook

import { useFormControlUnstyledContext } from '@mui/base/FormControlUnstyled';

The useFormControlUnstyledContext hook reads the context provided by Unstyled Form Control. This hook lets you work with custom input components inside of the Form Control. You can also use it to read the form control's state and react to its changes in a custom component.

Hooks do not support slot props, but they do support customization props.

The demo below shows how to integrate this hook with its component counterpart:

CustomInput is a wrapper around a native HTML <input> that adds Form Control integration.
ControlStateDisplay reads the state of the form control and displays it as text.

empty | not focused

Note that even though Form Control supports both controlled and uncontrolled-style APIs (i.e. it accepts value and defaultValue props), useFormControlUnstyledContext returns only the controlled value. This way, you don't have to implement both in your custom input—Unstyled Form Control does this for you.

useFormControlUnstyledContext returns an object with the following fields:

Name	Type	Description
`disabled`	boolean	Represents the value of the FormControlUnstyled's `disabled` prop.
`error`	boolean	Represents the value of the Unstyled Form Control component's `error` prop. Note that it is not calculated automatically (i.e. it's not set when `required: true` and `value: ''`).
`filled`	boolean	Set to `true` if `value` is not empty.
`focused`	boolean	Set to `true` if the wrapped input has received focus.
`required`	boolean	Represents the value of the Unstyled Form Control component's `required` prop.
`value`	unknown	The current value of the form control.

The following callbacks are also part of the returned object—they are meant to be used when creating custom inputs:

Name	Type	Description
`onChange`	React.ChangeEvent => void	Value change handler. Should be forwarded to the inner input.
`onBlur`	() => void	Focus change handler. Should be forwarded to the inner input.
`onFocus`	() => void	Focus change handler. Should be forwarded to the inner input.

Customization

Accessing the form control state

You can access the state of the form control by providing a function as a child of the Form Control. The state will be provided as a parameter to this function.

The following demo shows how to access the state of the form control in an Unstyled Input component nested inside of the Form Control:

<FormControlUnstyled defaultValue="" required>
  {({ filled, focused }: FormControlUnstyledState) => (
    <React.Fragment>
      <Input className={filled ? 'filled' : ''} />
      {filled && !focused && <OkMark>✔</OkMark>}
    </React.Fragment>
  )}
</FormControlUnstyled>

<FormControlUnstyled defaultValue="" required>
  {({ filled, focused }: FormControlUnstyledState) => (
    <React.Fragment>
      <Input className={filled ? 'filled' : ''} />
      {filled && !focused && <OkMark>✔</OkMark>}
    </React.Fragment>
  )}
</FormControlUnstyled>

Press Enter to start editing

FormControlUnstyled API

Import

import FormControlUnstyled from '@mui/base/FormControlUnstyled';
// or
import { FormControlUnstyled } from '@mui/base';

You can learn about the difference by reading this guide on minimizing bundle size.

Props

Props of the native component are also available.

Name	Type	Default	Description
children	node \| func		The content of the component.
component	elementType		The component used for the root node. Either a string to use a HTML element or a component.
disabled	bool	false	If `true`, the label, input and helper text should be displayed in a disabled state.
error	bool	false	If `true`, the label is displayed in an error state.
onChange	func		Callback fired when the form element's value is modified.
required	bool	false	If `true`, the label will indicate that the `input` is required.
slotProps	{ root?: func \| object }	{}	The props used for each slot inside the FormControl.
slots	{ root?: elementType }	{}	The components used for each slot inside the FormControl. Either a string to use a HTML element or a component. See Slots API below for more details.
value	any		The value of the form element.

The ref is forwarded to the root element.

useFormControlUnstyledContext API

Import

import useFormControlUnstyledContext from '@mui/base/FormControlUnstyled';
// or
import { useFormControlUnstyledContext } from '@mui/base';

You can learn about the difference by reading this guide on minimizing bundle size.

Parameters

Name	Type	Default	Description

Return value

Name	Type	Default	Description
filled	boolean		If `true`, the form element has some value.
focused	boolean		If `true`, the form element is focused and not disabled.
onBlur	() => void		Callback fired when the form element has lost focus.
onFocus	() => void		Callback fired when the form element receives focus.
disabled^?	boolean	false	If `true`, the label, input and helper text should be displayed in a disabled state.
error^?	boolean	false	If `true`, the label is displayed in an error state.
onChange^?	React.ChangeEventHandler<NativeFormControlElement>		Callback fired when the form element's value is modified.
required^?	boolean	false	If `true`, the label will indicate that the `input` is required.
value^?	unknown		The value of the form element.