jb-pin-input

jb-pin-input

jb-pin-input is a standalone, form-associated web component for PIN, OTP, and one-time-code entry.

• Renders one input cell per character.
• Supports configurable PIN length with charLength / char-length.
• Accepts Persian and Arabic digits and stores English digits.
• Supports smart paste from text that contains a full or partial PIN.
• Moves focus between cells while typing, deleting, and using left/right arrows.
• Dispatches complete event when all cells are filled and validation passes.
• Uses jb-validation for custom validation and built-in required validation.

When to use

Use jb-pin-input for OTP, verification code, PIN, and short numeric code entry.

Use jb-password-input for secret text that should be masked as a password. Use jb-input for normal single-field text entry.

Demo

• CodePen
• GitHub Pages
• Storybook

Using With JS Frameworks

• 

Installation

npm i jb-pin-input

import 'jb-pin-input';

<jb-pin-input label="Verification code" name="otp" char-length="6" message="Enter verification code"></jb-pin-input>

CDN

<script src="https://unpkg.com/jb-pin-input"></script>

API reference

Attributes

name	type	default	description
value	string	""	Initial or reflected PIN value. Missing cells are represented by - in .value.
char-length	number	6	Number of PIN cells.
name	string	""	Form field name.
label	string	""	Accessible label used for the PIN group and each internal cell.
accessible-label	string	""	Accessible label fallback when you do not want to use label.
required	boolean	false	Enables required validation. Empty attribute and "true" mean true.
disabled	boolean	false	Disables all inner PIN inputs. Empty attribute and "true" mean true.
autofocus	boolean	false	Focuses the first input after initialization. Empty attribute and "true" mean true.
inputmode	string	numeric	Input mode forwarded to each internal input.
message	string	""	Helper text shown below the PIN cells when no validation error is visible.
error	string	""	External validation error message.
disable-auto-validation	boolean	false	Disables automatic validation on blur when set to an empty attribute or "true".

Properties

name	type	readonly	description
value	string	no	Canonical PIN value. Empty cells are represented by -.
charLength	number	no	Number of PIN cells. See the charLength demo.
emptyChar	'-'	yes	Character used in .value for empty cells.
inputMode	string	no	Input mode forwarded to each internal input.
disabled	boolean	no	Enables or disables all inner inputs.
required	boolean	no	Enables required validation.
validation	ValidationHelper<string>	yes	Validation helper from jb-validation; set validation.list for custom rules. See the validation demo.
form	HTMLFormElement | null	yes	Associated form from ElementInternals.
name	string	yes	Form field name from the name attribute.
isDirty	boolean	yes	true when current value differs from initialValue.
validationMessage	string | null	yes	Current validation message from ElementInternals.

Methods

name	returns	description
checkValidity()	boolean	Runs validation without showing the error message. Dispatches invalid when invalid.
reportValidity()	boolean	Runs validation and shows the first error message. Dispatches invalid when invalid.
focus()	void	Focuses the first empty cell, or the last cell when all cells are filled.
clearValidationError()	void	Clears the visible validation error and restores message.

Events

event	description
load	Dispatched from connectedCallback before initialization.
init	Dispatched from connectedCallback after initialization.
beforeinput	Re-dispatched from the active inner input.
input	Dispatched after a PIN cell changes.
change	Dispatched on blur when the PIN value changed during focus.
keydown	Re-dispatched from the active inner input.
keyup	Re-dispatched from the active inner input.
keypress	Re-dispatched from the active inner input.
enter	Dispatched when Enter is pressed.
complete	Dispatched after the last cell is filled and validation passes.
invalid	Dispatched when checkValidity() or reportValidity() fails.

Value

The default length is 6. Empty cells are represented by - in .value.

const pinInput = document.querySelector('jb-pin-input');

pinInput.value = '1234';
console.log(pinInput.value); // "1234--"

<jb-pin-input value="123456"></jb-pin-input>

The component accepts Persian and Arabic digits and stores English digits.

Character length

const pinInput = document.querySelector('jb-pin-input');

pinInput.charLength = 5;

<jb-pin-input char-length="5"></jb-pin-input>

Smart paste

When pasted text contains a full PIN with the configured length, the component extracts that PIN. If no full match exists, it extracts the first partial digit sequence and fills from the current cell.

Validation

Use required for the common required rule. It is valid only when all cells are filled.

<jb-pin-input required></jb-pin-input>

Use validation.list for custom rules. For advanced validators, async validation, and validation result options, see jb-validation.

const pinInput = document.querySelector('jb-pin-input');

pinInput.validation.list = [
  {
    validator: /^1234--$/g,
    message: 'Only 1234 is accepted',
  },
  {
    validator: (value) => value.startsWith('1'),
    message: 'PIN must start with 1',
  },
];

const isValid = pinInput.checkValidity();
const isVisibleValid = pinInput.reportValidity();

Autofocus

<jb-pin-input autofocus></jb-pin-input>

CSS parts and variables

See the Storybook styling demos for examples using CSS variables and ::part(...).

part	description
inputs-wrapper	Wrapper around all PIN cells. Useful for layout-level styling.
input-wrapper	Every PIN cell wrapper.
input-wrapper-{index}	A specific PIN cell wrapper, starting from 0; for example input-wrapper-0.
pin-input	Every internal input element.
pin-input-{index}	A specific internal input element, starting from 0; for example pin-input-0.
input-line	Every bottom line element below a PIN input.
input-line-{index}	A specific bottom line element, starting from 0; for example input-line-0.
message	Helper or validation message element.

CSS variable name	description
--jb-pin-input-inputs-wrapper-width	Width of the inputs wrapper.
--jb-pin-input-inputs-gap	Gap between PIN cells.
--jb-pin-input-bottom-line-color	Bottom line color.
--jb-pin-input-bottom-line-border-radius	Bottom line border radius.
--jb-pin-input-bottom-line-height	Bottom line height.
--jb-pin-input-bottom-line-display	Bottom line display value.
--jb-pin-input-bottom-line-color-active	Bottom line color while focused.
--jb-pin-input-wrapper-border-width	Cell wrapper border width.
--jb-pin-input-wrapper-border-color	Cell wrapper border color.
--jb-pin-input-wrapper-border-style	Cell wrapper border style.
--jb-pin-input-wrapper-border-color-active	Cell wrapper border color while focused.
--jb-pin-input-wrapper-border-radius	Cell wrapper border radius.
--jb-pin-input-wrapper-box-shadow	Cell wrapper box shadow while focused.
--jb-pin-input-pin-color	PIN text color.
--jb-pin-input-pin-height	Cell input height.
--jb-pin-input-pin-font-size	Cell input font size.
--jb-pin-input-pin-font-weight	Cell input font weight.
--jb-pin-input-message-box-display	Message box display value.
--jb-pin-input-message-color	Message text color.
--jb-pin-input-message-error-color	Error message text color.
--jb-pin-input-message-font-size	Message font size.
--jb-pin-input-message-margin	Message box margin.

jb-pin-input {
  --jb-pin-input-inputs-wrapper-width: 320px;
  --jb-pin-input-inputs-gap: 12px;
  --jb-pin-input-bottom-line-color-active: #0f766e;
  --jb-pin-input-pin-font-size: 28px;
}

jb-pin-input::part(input-wrapper) {
  background: #ffffff;
}

jb-pin-input::part(input-line-0) {
  background: #0f766e;
}

Accessibility notes

• The component is form-associated and submits .value as its form value.
• The component uses multiple internal inputs with inputmode="numeric" by default. Each internal cell receives an accessible name in the form Verification code, digit 1 of 6.
• Set label, accessible-label, or aria-label on <jb-pin-input> so assistive technologies receive a useful name. The label attribute is not rendered visually, so add a visible label in your app layout when needed.
• The first internal input uses autocomplete="one-time-code" for OTP autofill support.
• Helper and validation messages are connected to each internal input with aria-describedby; visible errors also set aria-invalid and aria-errormessage.

Related Docs

• See jb-pin-input/react if you want to use this component in React.
• See All JB Design System Component List for more components.
• Use Contribution Guide if you want to contribute to this component.

AI agent notes

• Import jb-pin-input once before using <jb-pin-input>.
• Use char-length in HTML and charLength in JavaScript/React.
• .value includes - for empty cells, so a partially entered value may look like "12----".
• Listen to complete for the moment all cells are filled and validation passes.
• Use label, accessible-label, or aria-label to provide the accessible name for the generated PIN cells.
• Listen to change for a committed value change after blur.
• This package includes custom-elements.json and points to it with the package.json customElements field. The field is documented by the Custom Elements Manifest project in Referencing manifests from npm packages.
• In custom-elements.json, exports.kind: "js" describes JavaScript/TypeScript exports and exports.kind: "custom-element-definition" maps the jb-pin-input tag name to JBPinInputWebComponent.