> Leaf UI 0.8.1 · Package: @ifhover/leaf-ui · Source: 435bab23cad7d343653d9b63b049c0b0601eeefb
> Browser documentation: https://ifhover.github.io/leaf-ui/en/components/input-mask.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/en/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/en/llms-full.txt.

# InputMask

Enter information in a specified format.

## Basic usage


Unmasked value: —

basic.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/input-mask/basic.tsx"
import { InputMask, Space, Text } from '@ifhover/leaf-ui';

import { useState } from 'react';

export function InputMaskBasic() {
  const [value, setValue] = useState('');
  return (
    <Space direction="vertical" align="stretch">
      <InputMask
        mask="+{86} 000 0000 0000"
        placeholder="+86 138 0000 0000"
        unmask
        value={value}
        onChange={setValue}
        aria-label="Phone number"
      />
      <output>
        <Text tone="muted">Unmasked value: {value || '—'}</Text>
      </output>
    </Space>
  );
}
```

Expand code

## More examples


Card number formatCustom letter and digit rules

advanced.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/input-mask/advanced.tsx"
import { InputMask, Space, Text } from '@ifhover/leaf-ui';

export function InputMaskFormats() {
  return (
    <Space direction="vertical" align="stretch">
      <Text tone="muted">Card number format</Text>
      <InputMask mask="0000 0000 0000 0000" lazy={false} aria-label="Card number" />
      <Text tone="muted">Custom letter and digit rules</Text>
      <InputMask
        mask="AA-0000"
        definitions={{ A: /[A-Z]/ }}
        placeholder="AB-1234"
        aria-label="Identifier"
      />
    </Space>
  );
}
```

Expand code

## Usage

Mask characters are 0 for digits, a for letters and \* for alphanumeric. Validate business rules in your application. unmask affects component values and callbacks; native form submission uses the display value.

## Types

Import these types for data, callbacks and refs.

```ts
import type { InputMaskProps } from '@ifhover/leaf-ui';
```

## InputMaskProps API

| Property       | Type                                                            | Default  | Description                                               |
| -------------- | --------------------------------------------------------------- | -------- | --------------------------------------------------------- |
| `size`         | `'sm' \| 'md' \| 'lg'`                                          | `'md'`   | Size or spacing preset                                    |
| `status`       | `'error' \| 'warning'`                                          | —        | Display state                                             |
| `prefix`       | `ReactNode`                                                     | —        | Content before the input                                  |
| `suffix`       | `ReactNode`                                                     | —        | Content after the input                                   |
| `allowClear`   | `boolean`                                                       | `false`  | Show the clear button                                     |
| `onClear`      | `() => void`                                                    | —        | Called after clearing the input                           |
| `showCount`    | `boolean \| ((value: string, maxLength?: number) => ReactNode)` | `false`  | Display count or a custom renderer                        |
| `onPressEnter` | `KeyboardEventHandler<HTMLInputElement>`                        | —        | Called when Enter is pressed                              |
| `mask`         | `string`                                                        | Required | Pattern: 0 for digits, a for letters, \* for alphanumeric |
| `definitions`  | `Record<string, RegExp>`                                        | —        | Custom character rules                                    |
| `lazy`         | `boolean`                                                       | `true`   | Show placeholders as needed                               |
| `unmask`       | `boolean`                                                       | `false`  | Use unmasked values and callbacks                         |
| `value`        | `string`                                                        | —        | Controlled value                                          |
| `defaultValue` | `string`                                                        | `''`     | Initial value, restored by uncontrolled form resets       |
| `onChange`     | `(value: string, formatted: string) => void`                    | —        | Value change callback                                     |
| `onComplete`   | `(value: string) => void`                                       | —        | Called when input is complete                             |