# Code input

A numeric code input rendered as individual cells, for passcodes, one-time passwords (OTP) and authenticator (TOTP) codes.

Tabs: [Guidelines](/components/web/code-input/code-input.guidelines.md) · [Code](/components/web/code-input/code-input.code.md)

## Basic usage

First, import the component.

```tsx
import {CodeInput} from '@pleo-io/telescope'
```

Then use it like so:

```tsx
import {CodeInput} from '@pleo-io/telescope'
;<CodeInput length={6} label="Verification code" autoCompleteOneTimeCode />
```

The field uses `inputMode="numeric"` and rejects non-digit input after trimming surrounding whitespace. `autoCompleteOneTimeCode` enables the browser's `one-time-code` autofill hint for SMS codes.

See the [API reference](https://telescope.pleo.io/components/web/code-input/code-input.code#api-reference) for all props and [Guidelines](https://telescope.pleo.io/components/web/code-input/code-input.guidelines) for when and why to use the various options.

***

## Examples

### Passcode

`reveal` controls how digits are shown: `visible` (default), `masked` (hidden behind `•`) or `peek` (masked, but the last typed digit is shown for one second). `masked` and `peek` use a password input.

```tsx
import {CodeInput} from '@pleo-io/telescope'
;<CodeInput length={4} label="Passcode" reveal="peek" />
```

### Authenticator code

`split` sets the number of cells per dash-separated group. For example, `split={3}` on a six-digit code gives two groups of three.

```tsx
import {CodeInput} from '@pleo-io/telescope'
;<CodeInput length={6} split={3} label="Authenticator code" />
```

### Callbacks and reset

- `onChange` receives the current value on each accepted change.
- `onComplete` receives the code whenever an accepted change fills every cell.
- `onIncompleteSubmit` runs when the field's form is submitted with an incomplete code. Pressing Enter submits the form, but an empty field is blocked by native required-field validation.

To clear the code from outside, for example after a failed verification, attach a ref typed `CodeInputRef` and call `reset()`. It also calls `onChange` with an empty string and moves focus back to the field.

```tsx
import {useRef} from 'react'
import {CodeInput} from '@pleo-io/telescope'
import type {CodeInputRef} from '@pleo-io/telescope'

export function VerificationCode({verify}: {verify: (code: string) => Promise<boolean>}) {
    const ref = useRef<CodeInputRef>(null)

    const handleComplete = async (code: string) => {
        const isValid = await verify(code)
        if (!isValid) {
            ref.current?.reset()
        }
    }

    return <CodeInput ref={ref} length={6} label="Verification code" onComplete={handleComplete} />
}
```

***

## Accessibility

`label` is required and becomes the input's `aria-label`. Pass an already translated string: the component ships no default label.

`isInvalid` sets `aria-invalid` on the input as well as the visual error state on the cells.

## API reference

#### `autoCompleteOneTimeCode`

Type: `boolean`

Default: `false`

No description available

#### `autoFocus`

Type: `boolean`

Default: `false`

No description available

#### `compact`

Type: `boolean`

Default: `false`

No description available

#### `data-testid`

Type: `string | undefined`

Default: -

No description available

#### `isInvalid`

Type: `boolean`

Default: `false`

No description available

#### `label` (required)

Type: `string`

Default: -

No description available

#### `length` (required)

Type: `number`

Default: -

No description available

#### `name`

Type: `string | undefined`

Default: `code-input`

No description available

#### `onChange`

Type: `((value: string) => void) | undefined`

##### Allowed values

- `(value: string) => void`

Default: -

No description available

#### `onComplete`

Type: `((value: string) => void) | undefined`

##### Allowed values

- `(value: string) => void`

Default: -

No description available

#### `onIncompleteSubmit`

Type: `(() => void) | undefined`

##### Allowed values

- `() => void`

Default: -

No description available

#### `reveal`

Type: `"visible" | "masked" | "peek" | undefined`

Default: `visible`

No description available

#### `split`

Type: `number | undefined`

Default: -

No description available
