OtpInput

Playground

Gõ hoặc dán cả chữ và số vào ô — chỉ chữ số còn lại. Đổi length và error để xem OtpInput thích ứng.

import { OtpInput } from "@nexobox/ui";

function Example() {
  const [value, setValue] = useState("");
  return (
    <OtpInput
      label="Mã xác thực"
      value={value}
      onChange={setValue}
      length={6}
    />
  );
}

Bài toán

Người dùng nhận một mã sáu chữ số và phải đưa nó vào ứng dụng, và việc đó thành công hay thất bại gần như hoàn toàn nhờ tự điền: nếu hệ điều hành đề nghị mã ngay trên bàn phím thì thao tác còn một lần chạm. Một Input trần không đủ vì tự điền chỉ kích hoạt khi có đúng tổ hợp autoComplete="one-time-code", inputMode="numeric" và pattern; và một mã dán từ bộ nhớ tạm thường mang theo khoảng trắng hoặc dấu gạch, nên cần một bộ lọc. Ba thuộc tính cộng một bộ lọc cộng một maxLength suy từ độ dài mã — năm quyết định không thuộc về Input, và gom chúng lại chính là composite này. Một Field cũng không làm được: Field truyền thẳng props và không lọc giá trị.

Khi nào sử dụng

Nên dùng

Nhập mã xác thực một lần: xác minh email, MFA, xác nhận thiết bị. Mã có độ dài biết trước, mặc định sáu chữ số, đổi được bằng length. Bề mặt di động, nơi tự điền là khác biệt lớn nhất giữa dùng được và không.

Khi nào không dùng

Tránh dùng

Dựng từ

Anatomy

Không có ô thứ hai, không có dấu phân tách, không có ô trống đếm số ký tự còn lại. Một ô, và chữ giãn làm việc mà sáu hộp định làm.

States

Đủ độ dài: ô không tự nộp — việc nộp là của host. Hover, focus, disabled: kế thừa từ Input. Unknown — không có trạng thái loading: trong lúc host đang xác thực mã, việc khoá ô hay hiện chỉ báo do host làm.

Bàn phím & trợ năng

Seam — host sở hữu gì

OtpInput không xác thực mã, không gọi gì, không tự nộp khi đủ số ký tự, và không đếm số lần thử. Theo ADR-UI-003 clause 2 nó không fetch, không đọc router, không giữ session, không import gì từ next. Clause 6: không mảnh nào của phần bảo mật mô phỏng trong bộ kit được port, nên composite này không biết mã nào là đúng và không được dạy để biết.

API & triển khai

Design tokens

OtpInput đọc --nf-component-auth-field-gap, --nf-foundation-typography-data-font-family, --nf-foundation-typography-caption-font-size, -caption-line-height, --nf-semantic-status-danger-foreground. Hai giá trị chưa thành token, ghi ra thay vì che: letter-spacing: 0.5em và cỡ chữ 1.25rem của dãy số là số trần trong file — corpus chưa có vai "chữ mã" nên chưa có alias.

Do / Don't