Credit Card

Web/Mobile

A labeled card-number field with four digit groups, separators, description, and error. Values always display as Persian digits.

Base UI React Aria Radix UI

Registry API Reference

شماره کارت

لطفاً شماره کارت را در چهار گروه چهاررقمی وارد کنید.

"use client"

import {
  CreditCard,
  CreditCardControl,
  CreditCardDescription,
  CreditCardGroup1,
  CreditCardGroup2,
  CreditCardGroup3,
  CreditCardGroup4,
  CreditCardLabel,
  CreditCardSeparator,
} from "@/components/cubix/credit-card"

export function CreditCardDemo() {
  return (
    <CreditCard className="w-full max-w-sm">
      <CreditCardLabel>شماره کارت</CreditCardLabel>
      <CreditCardControl>
        <CreditCardGroup1 />
        <CreditCardSeparator />
        <CreditCardGroup2 />
        <CreditCardSeparator />
        <CreditCardGroup3 />
        <CreditCardSeparator />
        <CreditCardGroup4 />
      </CreditCardControl>
      <CreditCardDescription>
        لطفاً شماره کارت را در چهار گروه چهاررقمی وارد کنید.
      </CreditCardDescription>
    </CreditCard>
  )
}

Installation

pnpm dlx cubix-ui@latest add credit-card --base aria

Usage

Import

import {
  CreditCard,
  CreditCardControl,
  CreditCardDescription,
  CreditCardGroup1,
  CreditCardGroup2,
  CreditCardGroup3,
  CreditCardGroup4,
  CreditCardLabel,
  CreditCardSeparator,
} from "@/components/cubix/credit-card"

Example

<CreditCard className="w-full max-w-sm">
  <CreditCardLabel>شماره کارت</CreditCardLabel>
  <CreditCardControl>
    <CreditCardGroup1 />
    <CreditCardSeparator />
    <CreditCardGroup2 />
    <CreditCardSeparator />
    <CreditCardGroup3 />
    <CreditCardSeparator />
    <CreditCardGroup4 />
  </CreditCardControl>
  <CreditCardDescription>
    لطفاً شماره کارت را در چهار گروه چهاررقمی وارد کنید.
  </CreditCardDescription>
</CreditCard>

Composition

Compose label, control, help text, and error under CreditCard. Inside the control, four groups of four digits sit between CreditCardSeparator parts. Digits always display in Persian. Filling a group moves focus to the next; Backspace on an empty group moves back. Paste a full number to fill all groups.

Structure

CreditCard
├── CreditCardLabel
├── CreditCardControl
│   ├── CreditCardGroup1
│   ├── CreditCardSeparator
│   ├── CreditCardGroup2
│   ├── CreditCardSeparator
│   ├── CreditCardGroup3
│   ├── CreditCardSeparator
│   └── CreditCardGroup4
├── CreditCardDescription
└── CreditCardError

Accessibility

Each group has its own accessible name. Auto-advance and Backspace keep keyboard entry on one path. CreditCardDescription and CreditCardError are announced through aria-describedby, and invalid sets aria-invalid on every group. Set name on the root to submit a single hidden value for the full card number.

Examples

Description

Add helper text below the control for format hints or guidance.

شماره کارت

لطفاً شماره کارت را در چهار گروه چهاررقمی وارد کنید.

"use client"

import {
  CreditCard,
  CreditCardControl,
  CreditCardDescription,
  CreditCardGroup1,
  CreditCardGroup2,
  CreditCardGroup3,
  CreditCardGroup4,
  CreditCardLabel,
  CreditCardSeparator,
} from "@/components/cubix/credit-card"

export function CreditCardDescriptionDemo() {
  return (
    <CreditCard className="w-full max-w-sm">
      <CreditCardLabel>شماره کارت</CreditCardLabel>
      <CreditCardControl>
        <CreditCardGroup1 />
        <CreditCardSeparator />
        <CreditCardGroup2 />
        <CreditCardSeparator />
        <CreditCardGroup3 />
        <CreditCardSeparator />
        <CreditCardGroup4 />
      </CreditCardControl>
      <CreditCardDescription>
        لطفاً شماره کارت را در چهار گروه چهاررقمی وارد کنید.
      </CreditCardDescription>
    </CreditCard>
  )
}

Filled

Pass defaultValue on each group to show a complete card number.

شماره کارت

لطفاً شماره کارت را در چهار گروه چهاررقمی وارد کنید.

"use client"

import {
  CreditCard,
  CreditCardControl,
  CreditCardDescription,
  CreditCardGroup1,
  CreditCardGroup2,
  CreditCardGroup3,
  CreditCardGroup4,
  CreditCardLabel,
  CreditCardSeparator,
} from "@/components/cubix/credit-card"

export function CreditCardFilledDemo() {
  return (
    <CreditCard className="w-full max-w-sm">
      <CreditCardLabel>شماره کارت</CreditCardLabel>
      <CreditCardControl>
        <CreditCardGroup1 defaultValue="۶۱۰۴" />
        <CreditCardSeparator />
        <CreditCardGroup2 defaultValue="۳۳۹۹" />
        <CreditCardSeparator />
        <CreditCardGroup3 defaultValue="۱۲۳۴" />
        <CreditCardSeparator />
        <CreditCardGroup4 defaultValue="۵۶۷۸" />
      </CreditCardControl>
      <CreditCardDescription>
        لطفاً شماره کارت را در چهار گروه چهاررقمی وارد کنید.
      </CreditCardDescription>
    </CreditCard>
  )
}

Invalid

Set invalid on the root to apply destructive styles and show CreditCardError.

شماره کارت

یک شماره کارت معتبر وارد کنید.

"use client"

import {
  CreditCard,
  CreditCardControl,
  CreditCardError,
  CreditCardGroup1,
  CreditCardGroup2,
  CreditCardGroup3,
  CreditCardGroup4,
  CreditCardLabel,
  CreditCardSeparator,
} from "@/components/cubix/credit-card"

export function CreditCardInvalidDemo() {
  return (
    <CreditCard className="w-full max-w-sm" invalid>
      <CreditCardLabel>شماره کارت</CreditCardLabel>
      <CreditCardControl>
        <CreditCardGroup1 defaultValue="۶۰۳۷" />
        <CreditCardSeparator />
        <CreditCardGroup2 defaultValue="۹۹۷۷" />
        <CreditCardSeparator />
        <CreditCardGroup3 defaultValue="۱۲۳۴" />
        <CreditCardSeparator />
        <CreditCardGroup4 defaultValue="۰۰" />
      </CreditCardControl>
      <CreditCardError>یک شماره کارت معتبر وارد کنید.</CreditCardError>
    </CreditCard>
  )
}

Disabled

Disable the field to block every group. The control uses a muted fill; label and description stay readable.

شماره کارت

این فیلد فعلاً قابل ویرایش نیست.

"use client"

import {
  CreditCard,
  CreditCardControl,
  CreditCardDescription,
  CreditCardGroup1,
  CreditCardGroup2,
  CreditCardGroup3,
  CreditCardGroup4,
  CreditCardLabel,
  CreditCardSeparator,
} from "@/components/cubix/credit-card"

export function CreditCardDisabledDemo() {
  return (
    <CreditCard className="w-full max-w-sm" disabled>
      <CreditCardLabel>شماره کارت</CreditCardLabel>
      <CreditCardControl>
        <CreditCardGroup1 />
        <CreditCardSeparator />
        <CreditCardGroup2 />
        <CreditCardSeparator />
        <CreditCardGroup3 />
        <CreditCardSeparator />
        <CreditCardGroup4 />
      </CreditCardControl>
      <CreditCardDescription>این فیلد فعلاً قابل ویرایش نیست.</CreditCardDescription>
    </CreditCard>
  )
}

Sizes

Two heights ship by default: default (40px) and lg (48px). Use className for any other size.

شماره کارت

ارتفاع ۴۰ پیکسل

شماره کارت

ارتفاع ۴۸ پیکسل

"use client"

import {
  CreditCard,
  CreditCardControl,
  CreditCardDescription,
  CreditCardGroup1,
  CreditCardGroup2,
  CreditCardGroup3,
  CreditCardGroup4,
  CreditCardLabel,
  CreditCardSeparator,
} from "@/components/cubix/credit-card"

export function CreditCardSizesDemo() {
  return (
    <div className="grid w-full max-w-sm gap-8">
      <CreditCard size="default">
        <CreditCardLabel>شماره کارت</CreditCardLabel>
        <CreditCardControl>
          <CreditCardGroup1 />
          <CreditCardSeparator />
          <CreditCardGroup2 />
          <CreditCardSeparator />
          <CreditCardGroup3 />
          <CreditCardSeparator />
          <CreditCardGroup4 />
        </CreditCardControl>
        <CreditCardDescription>ارتفاع ۴۰ پیکسل</CreditCardDescription>
      </CreditCard>
      <CreditCard size="lg">
        <CreditCardLabel>شماره کارت</CreditCardLabel>
        <CreditCardControl>
          <CreditCardGroup1 />
          <CreditCardSeparator />
          <CreditCardGroup2 />
          <CreditCardSeparator />
          <CreditCardGroup3 />
          <CreditCardSeparator />
          <CreditCardGroup4 />
        </CreditCardControl>
        <CreditCardDescription>ارتفاع ۴۸ پیکسل</CreditCardDescription>
      </CreditCard>
    </div>
  )
}

In a form

Set name on the root so the combined number is submitted with the form, and pair the field with Cubix Button.

"use client"

import { Button } from "@/components/cubix/button"
import {
  CreditCard,
  CreditCardControl,
  CreditCardDescription,
  CreditCardGroup1,
  CreditCardGroup2,
  CreditCardGroup3,
  CreditCardGroup4,
  CreditCardLabel,
  CreditCardSeparator,
} from "@/components/cubix/credit-card"

export function CreditCardFormDemo() {
  return (
    <form
      className="grid w-full max-w-sm gap-6 rounded-xl bg-background p-6"
      onSubmit={(event) => event.preventDefault()}
    >
      <div className="space-y-1.5">
        <p className="text-body leading-none font-medium text-foreground">پرداخت</p>
        <p className="text-caption text-muted-foreground">
          برای ادامه، شماره کارت خود را وارد کنید.
        </p>
      </div>
      <CreditCard name="cardNumber">
        <CreditCardLabel>شماره کارت</CreditCardLabel>
        <CreditCardControl>
          <CreditCardGroup1 />
          <CreditCardSeparator />
          <CreditCardGroup2 />
          <CreditCardSeparator />
          <CreditCardGroup3 />
          <CreditCardSeparator />
          <CreditCardGroup4 />
        </CreditCardControl>
        <CreditCardDescription>
          لطفاً شماره کارت را در چهار گروه چهاررقمی وارد کنید.
        </CreditCardDescription>
      </CreditCard>
      <div className="grid grid-cols-2 gap-2">
        <Button type="button" variant="outline">
          انصراف
        </Button>
        <Button type="submit">ادامه</Button>
      </div>
    </form>
  )
}

Custom styling

Every part accepts a className merged with the shipped cn helper. Here each group uses a filled surface instead of the default outline.

شماره کارت

با className می‌توانید ظاهر را سفارشی کنید.

"use client"

import {
  CreditCard,
  CreditCardControl,
  CreditCardDescription,
  CreditCardGroup1,
  CreditCardGroup2,
  CreditCardGroup3,
  CreditCardGroup4,
  CreditCardLabel,
  CreditCardSeparator,
} from "@/components/cubix/credit-card"

export function CreditCardCustomDemo() {
  return (
    <CreditCard className="w-full max-w-sm">
      <CreditCardLabel>شماره کارت</CreditCardLabel>
      <CreditCardControl>
        <CreditCardGroup1 className="border-border bg-muted dark:bg-muted" />
        <CreditCardSeparator />
        <CreditCardGroup2 className="border-border bg-muted dark:bg-muted" />
        <CreditCardSeparator />
        <CreditCardGroup3 className="border-border bg-muted dark:bg-muted" />
        <CreditCardSeparator />
        <CreditCardGroup4 className="border-border bg-muted dark:bg-muted" />
      </CreditCardControl>
      <CreditCardDescription>با className می‌توانید ظاهر را سفارشی کنید.</CreditCardDescription>
    </CreditCard>
  )
}

API Reference

Note: Parts render data-slot attributes (credit-card, credit-card-label, credit-card-control, credit-card-group-1, credit-card-group-2, credit-card-group-3, credit-card-group-4, credit-card-separator, credit-card-description, credit-card-error) for targeting in tests and parent selectors. Use the same props on Base UI, React Aria, and Radix.

CreditCard

Prop	Type	Default	Description
size	"default" \| "lg"	"default"	Height for the control: default 40px, lg 48px. Inherited by CreditCardControl unless overridden. Use className for other heights.
disabled	boolean	false	Disables the field and prevents interaction. Forwarded to the segments on every base.
invalid	boolean	false	Marks the field as invalid and shows CreditCardError when present.
name	string	-	Writes a hidden input with the combined four-group value (Persian digits, hyphen-separated) for form submit.
className	string	-	Additional Tailwind classes merged with the root styles (last one wins).

CreditCardControl

Prop	Type	Default	Description
size	"default" \| "lg"	-	Overrides the size from CreditCard. Height matches the default and lg sizes.
children	React.ReactNode	-	Compose CreditCardGroup1-4 with CreditCardSeparator between them. The control is a layout row only (dir=ltr) - each group has its own input box.
className	string	-	Additional Tailwind classes merged with the control styles (last one wins).

CreditCardGroup1 / 2 / 3 / 4

Prop	Type	Default	Description
part	"group1" \| "group2" \| "group3" \| "group4"	-	Fixed by CreditCardGroup1-4. Each group accepts 4 digits and always displays Persian digits.
placeholder	string	-	Hint text shown when the segment is empty. Empty by default.
inputMode	"numeric"	"numeric"	Locked to numeric so mobile keyboards show a number pad.
className	string	-	Additional Tailwind classes merged with the segment styles (last one wins).
...props	Omit<React.ComponentProps<'input'>, 'type' \| 'inputMode' \| 'spellCheck' \| 'maxLength'>	-	Native input attributes (value, onChange, defaultValue, ...) are forwarded. type, inputMode, spellCheck, and maxLength stay locked. Use parseCreditCardValue / formatCreditCardValue for the combined string.

CreditCardSeparator

Prop	Type	Default	Description
children	React.ReactNode	"-"	Separator between card number groups. Defaults to -.
className	string	-	Additional Tailwind classes merged with the separator styles (last one wins).

CreditCardLabel / Description / Error

Prop	Type	Default	Description
children	React.ReactNode	-	For CreditCardDescription: shown as helper text until six digits match a known Iranian bank BIN, then replaced by the bank name (for example بانک ملت).
className	string	-	Additional Tailwind classes merged with the part styles (last one wins).
...props	HTML attributes	-	Native attributes for the rendered element are forwarded.