Mask Input

Installation

pnpm dlx shadcn@latest add @diceui/mask-input

Layout

Import and use the component directly.

import { MaskInput } from "@/components/ui/mask-input";
 
<MaskInput 
  mask="phone" 
  placeholder="Enter phone number"
  maskPlaceholder="(___) ___-____"
  onValueChange={(masked, unmasked) => {
    console.log('Masked:', masked);     // "(555) 123-4567"
    console.log('Unmasked:', unmasked); // "5551234567"
  }}
/>

Features

• Smart cursor positioning - Cursor stays in the correct position during typing and pasting
• Paste support - Intelligently handles pasted content with proper formatting
• Built-in patterns - Common formats like phone, SSN, date, credit card, etc.
• Custom patterns - Create your own mask patterns with validation
• Optional mask placeholders - Control when mask format hints are shown with maskPlaceholder
• TypeScript support - Full type safety with IntelliSense
• Accessibility - ARIA attributes and keyboard navigation
• Form integration - Works seamlessly with form libraries
• Composition support - Use render prop to render as a different component

Examples

With custom patterns

Create custom mask patterns for specific formatting needs.

With validation modes

Control when validation occurs with different validation modes, similar to react-hook-form.

Card information

Card information with credit card number, expiry date, and CVC fields.

With form

Integrate masked inputs with form validation using react-hook-form.

Built-in Mask Patterns

The component includes several predefined mask patterns:

Custom Mask Patterns

Create custom patterns using the MaskPattern interface:

const customPattern: MaskPattern = {
  pattern: "###-###-####",
  transform: (value, opts) => value.replace(/[^A-Z0-9]/gi, "").toUpperCase(),
  validate: (value, opts) => value.length === 10,
};
 
<MaskInput 
  mask={customPattern} 
  placeholder="Enter license plate"
  maskPlaceholder="ABC-1234"
/>

Currency Formatting

The currency mask uses the Intl.NumberFormat API for localization and currency formatting.

// Default USD formatting
<MaskInput mask="currency" />
 
// Euro formatting with German locale
<MaskInput 
  mask="currency" 
  currency="EUR" 
  locale="de-DE" 
/>
 
// Japanese Yen formatting
<MaskInput 
  mask="currency" 
  currency="JPY" 
  locale="ja-JP" 
/>
 
// British Pound formatting
<MaskInput 
  mask="currency" 
  currency="GBP" 
  locale="en-GB" 
/>

Mask Placeholders

Use the maskPlaceholder prop to control when mask format hints are shown. The mask placeholder only appears when the input is focused and the prop is provided.

// Shows mask placeholder when focused
<MaskInput 
  mask="phone" 
  placeholder="Enter phone number"
  maskPlaceholder="(___) ___-____"
/>
 
// No mask placeholder - just regular placeholder behavior
<MaskInput 
  mask="phone" 
  placeholder="Enter phone number"
/>

API Reference

MaskInput

The main masked input component that handles formatting and user input.

MaskPattern

Interface for creating custom mask patterns.

MaskPatternKey

Predefined mask pattern keys for common input formats.

TransformOptions

Options passed to the transform function for advanced formatting.

ValidateOptions

Options passed to the validate function for enhanced validation.

Data Attributes

Accessibility

Keyboard Interactions