## Feature Examples
### Size
- description: Control the size of the slots with the `size` prop. The default heights and text sizes match `` in every theme. - `medium` (default) - `large` for prominent screens, such as a full-page login step. - `small` and `tiny` for compact layouts. Use these sparingly.
- example:
```jsx
;
```
### Length
- description: Set the number of characters with the `length` prop. It's 6 by default. `onComplete` fires once the code reaches that length. On a narrow screen the row fits its container: the gaps between the slots get smaller first, then the slots get narrower, down to 60% of their width. Their height never changes, so they stay easy to tap.
- example:
```jsx
;
```
### Groups
- description: Split the slots into groups with `` and ``, for codes read in parts such as 123 456. - Groups next to each other are set apart by a wider gap. - Add `` between groups to draw a dash.
- example:
```jsx
;
```
### Status
- description: Set the status on the `` that wraps the field. The slots take on the status color and the `` shows the message below. The status only changes how the field looks; the entered code stays. - `error` marks a wrong code. Call `clear()` on the ref to empty it. - `warning` marks the field without an error. - `loading` marks the field as busy while a code is verified, and adds `readOnly` to stop edits meanwhile. It doesn't change the slots, so the field keeps its width. Show the progress in the `` message, with a tiny `` before the text.
- example:
```jsx
Verifying
}
>
;
```
### Status message
- description: Add text that explains the status or what to do next with the `statusMessage` prop of the ``. It is linked to the input, so a screen reader reads it.
- example:
```jsx
;
```
### Read only
- description: Stop edits with the `readOnly` prop, for example while a code is being verified. The code stays visible and can still be focused.
- example:
```jsx
;
```
### Disabled
- description: Disable the field with the `disabled` prop. It can't be focused or edited, and it doesn't show a status.
- example:
```jsx
;
```
### Auto focus
- description: Focus the field as soon as it appears with `autoFocus`, for example when a code step opens after the user asked for a code. Use it only when entering the code is the main task on the screen. Press _Show the code step_ to see the field appear focused.
- example:
```jsx
() => {
const [open, setOpen] = React.useState(false);
if (!open) {
return (
);
}
return (
setOpen(false)}>
Hide
);
};
```
### Typing and pasting
- description: The field behaves the way people expect from a code field. - Digits fill the slots from the left. Other characters are ignored. - Pasting a code fills the slots in order. Only digits are kept, and anything beyond the length is dropped. - Backspace deletes the last digit. - Clicking a filled slot selects its digit, so typing replaces it. - Arrow keys move between the slots.
- example:
```jsx
;
```
## Developer Examples
### Controlled and uncontrolled
- description: The field works in either mode, depending on whether you pass `value`. - **Uncontrolled:** leave out `value`. The field keeps the code itself, starting from `defaultValue`. Read it from `onChange` or `onComplete`, and empty it with `clear()` on the ref. - **Controlled:** pass `value` and update it in `onChange`. The field shows only what `value` holds, so you can set, change or empty the code from outside. `onChange` receives the code as a string of digits.
- example:
```jsx
() => {
const uncontrolled = React.useRef(null);
const [lastChange, setLastChange] = React.useState('12');
const [value, setValue] = React.useState('12');
return (
uncontrolled.current.clear()}>
Clear
Last onChange: {lastChange || '(empty)'}
setValue('123456')}>
Fill 123456
setValue('')}>
Clear
value: {value || '(empty)'}
);
};
```
### Verify the code
- description: Verify the code either when the last digit is typed, with `onComplete`, or when the user presses a button, with the code you keep from `onChange`. Show the result with the status of the `` and make the field `readOnly` while verifying. Without a button, show the progress in the `` message, with a tiny `` and the `loading` status. With a button, show it on the button and leave the status of the field empty. To let the user fix a wrong or incomplete code, keep it and call `focus()` on the ref: the cursor goes to the first empty slot, or the first slot of a complete code is selected so the user can retype it. Without a button, `onComplete` fires again when the last digit is retyped, or right away when the user clicks one digit and changes it.
- example:
```jsx
() => {
const useVerify = () => {
const code = React.useRef(null);
const [verifying, setVerifying] = React.useState(false);
const [status, setStatus] = React.useState(null);
const [message, setMessage] = React.useState(null);
const verify = value => {
if (value.length < 6) {
setStatus('error');
setMessage('Enter all 6 digits.');
code.current.focus();
return;
}
setStatus(undefined);
setMessage(undefined);
setVerifying(true);
setTimeout(() => {
setVerifying(false);
if (value === '123456') {
setMessage('Verified.');
} else {
setStatus('error');
setMessage('That code is wrong. Fix it and try again.');
code.current.focus();
}
}, 1200);
};
const reset = () => {
setStatus(undefined);
setMessage(undefined);
};
return { code, verifying, status, message, verify, reset };
};
const auto = useVerify();
const manual = useVerify();
const [value, setValue] = React.useState('');
return (
Verifying
) : (
auto.message
)
}
>
{
setValue(next);
manual.reset();
}}
/>
The right code is 123456. Enter another code to see the error, then fix it: retype it from the first slot, or click one digit and change it.
);
};
```
### In a form
- description: Give the field a `name` and the code is submitted with a native `
);
};
```
### Resend code
- description: Attach a ref to get `focus()` and `clear()`. `clear()` empties the code, calls `onChange` with an empty string and focuses the field.
- example:
```jsx
() => {
const code = React.useRef(null);
return (
code.current.clear()}>
Resend code
);
};
```
## Common Use Case Examples
### Two-step login
- description: A login step that asks for the code and lets the user ask for a new one.
- example:
```jsx
() => {
const code = React.useRef(null);
const [status, setStatus] = React.useState(null);
return (
Check your emailEnter the code sent to:name@example.com setStatus(undefined)}
onComplete={() => {
setStatus('error');
code.current.focus();
}}
/>
{
setStatus(undefined);
code.current.clear();
}}
>
Send a new code
);
};
```
### Confirm a phone number in a modal
- description: A modal that asks for the code sent to a new recovery phone number. Confirm checks that all six digits are entered. If not, it shows an error and keeps what was typed. A text button under the field sends a new code and clears it.
- example:
```jsx
() => {
const code = React.useRef(null);
const [value, setValue] = React.useState('');
const [status, setStatus] = React.useState(null);
const confirm = () => {
if (value.length < 6) {
setStatus('error');
code.current.focus();
}
};
return (
{}}
footnote={Note: Your code will expire after 10 mins.}
content={
{
setValue(next);
setStatus(undefined);
}}
/>
code.current.clear()}>
Resend code
}
/>
);
};
```
## Accessibility Examples
### Labels
- description: Label the field with the `label` of a ``. Screen readers meet one input with that name and the status message; the slots are only visual. - Without a ``, pass `ariaLabel`, or `ariaLabelledBy` with the `id` of an element that names the field, such as a heading.
- example:
```jsx
Recovery code
;
```