MaskInput

Input with mask pattern for formatted text entry

Usage

MaskInput is an input with a fixed format, for example a phone number or a credit card. The mask string defines the format, see mask pattern syntax. The component is built on top of the useMask hook:

Input description

Variant
Size
Radius
import { MaskInput } from '@mantine/core';

function Demo() {
  return (
    <MaskInput
      label="Input label"
      description="Input description"
      mask="(999) 999-9999"
      placeholder="(___) ___-____"
    />
  );
}

MaskInput with uncontrolled forms

Set name to submit the displayed text, including mask characters. defaultValue takes the raw value:

import { MaskInput } from '@mantine/core';

function Demo() {
  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        const data = new FormData(event.currentTarget);
        console.log(data.get('code'));
      }}
    >
      <MaskInput name="code" label="Code" mask="99-99" defaultValue="1234" />
      <button type="submit">Submit</button>
    </form>
  );
}

Dynamic mask

Use the modify option to change the mask based on the current value, for example to switch between standard and American Express credit card formats:

import { MaskInput } from '@mantine/core';

function Demo() {
  return (
    <MaskInput
      label="Credit card"
      placeholder="____ ____ ____ ____"
      mask="9999 9999 9999 9999"
      modify={(value) => {
        if (/^3[47]/.test(value)) {
          return { mask: '9999 999999 99999' };
        }
        return undefined;
      }}
    />
  );
}

Custom tokens

Override or extend the built-in token map with the tokens option:

import { MaskInput } from '@mantine/core';

function Demo() {
  return (
    <MaskInput
      label="Hex color"
      placeholder="#______"
      mask="\#hhhhhh"
      tokens={{ h: /[0-9a-fA-F]/ }}
    />
  );
}

Regex array format

When built-in tokens are not enough, pass an array of string literals and RegExp objects:

import { MaskInput } from '@mantine/core';

function Demo() {
  return (
    <MaskInput
      label="Time (HH:MM)"
      placeholder="__:__"
      mask={[/[0-2]/, /\d/, ':', /[0-5]/, /\d/]}
    />
  );
}

Transform

Use the transform option to convert each character before validation, for example to uppercase letters so that the A token accepts lowercase input:

Type lowercase letters – they will be auto-uppercased

import { MaskInput, Text } from '@mantine/core';

function Demo() {
  return (
    <>
      <MaskInput
        label="Promo code"
        placeholder="AAA-9999"
        mask="AAA-9999"
        transform={(char) => char.toUpperCase()}
        slotChar="XXX-0000"
      />
      <Text size="sm" mt="sm">
        Type lowercase letters – they will be auto-uppercased
      </Text>
    </>
  );
}

Disabled state

import { MaskInput } from '@mantine/core';

function Demo() {
  return (
    <MaskInput
      label="Phone number"
      placeholder="(___) ___-____"
      mask="(999) 999-9999"
      disabled
    />
  );
}

Error state

Invalid phone number

import { MaskInput } from '@mantine/core';

function Demo() {
  return (
    <MaskInput
      label="Phone number"
      placeholder="(___) ___-____"
      mask="(999) 999-9999"
      error="Invalid phone number"
    />
  );
}

Success state

Looks good!

import { MaskInput } from '@mantine/core';

function Demo() {
  return (
    <MaskInput
      label="Phone number"
      placeholder="(___) ___-____"
      mask="(999) 999-9999"
      success="Looks good!"
    />
  );
}

Controlled

value, defaultValue and onChange work with the raw value without the mask, for example 1234567890 for (123) 456-7890. Use onChangeRaw to get both raw and masked values:

import { useState } from 'react';
import { MaskInput } from '@mantine/core';

function Demo() {
  const [value, setValue] = useState('');

  return (
    <MaskInput
      mask="(999) 999-9999"
      value={value}
      onChange={setValue}
      onChangeRaw={(raw, masked) => console.log(raw, masked)}
      onComplete={(masked, raw) => console.log(masked, raw)}
    />
  );
}

Reset value

To clear a controlled input, set value to an empty string. In uncontrolled mode, use the resetRef prop to get a function that clears the input:

import { useRef } from 'react';
import { MaskInput, Button, Group } from '@mantine/core';

function Demo() {
  const resetRef = useRef<() => void>(null);

  return (
    <>
      <MaskInput
        label="Phone number"
        placeholder="(___) ___-____"
        mask="(999) 999-9999"
        resetRef={resetRef}
      />

      <Group mt="md">
        <Button onClick={() => resetRef.current?.()}>Reset</Button>
      </Group>
    </>
  );
}

With use-form

MaskInput works with use-form like any other input. The form receives the raw value without the mask, for example 1234567890 for (123) 456-7890. Values passed to initialValues, form.setFieldValue and form.reset must be raw values too:

import { Button, MaskInput } from '@mantine/core';
import { useForm } from '@mantine/form';

function Demo() {
  const form = useForm({
    initialValues: { phone: '' },
  });

  return (
    <form onSubmit={form.onSubmit((values) => console.log(values))}>
      <MaskInput
        mask="(999) 999-9999"
        placeholder="(___) ___-____"
        label="Phone"
        {...form.getInputProps('phone')}
      />

      <Button type="submit" mt="md">
        Submit
      </Button>
    </form>
  );
}

Mask pattern syntax

Each character of the mask string is either a token, an editable slot, or a literal, a fixed character inserted automatically.

Built-in tokens

  • 9 – any single digit ([0-9])
  • a – any single letter ([A-Za-z])
  • A – any uppercase letter ([A-Z])
  • * – any alphanumeric character ([A-Za-z0-9])
  • # – digit or sign ([-+0-9])

Optional segments

Append ? after the last required character to mark remaining slots as optional. When the input is not focused, the empty optional part is hidden. With alwaysShowMask, it stays visible with slot characters:

<MaskInput mask="(999) 999-9999? x9999" /> // Extension is optional

Escaping

Prefix a token character with \ to treat it as a literal:

<MaskInput mask="\A999" /> // "A" is literal, not a token