Skip to main content
Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

PinPad

The PinPad component provides a secure numeric keypad interface for PIN entry and validation. Use it to collect PIN codes, passcodes, or other sensitive numeric input with proper masking and validation.

The component provides a secure numeric input interface specifically designed for PIN entry, with visual feedback that masks entered digits for security. It includes built-in validation for PIN length requirements, supports error states for invalid PINs, and provides haptic feedback on touch-enabled devices to confirm key presses during secure authentication workflows.

PinPad components meets security standards for PIN entry by preventing screenshot capture and display recording, protecting sensitive authentication data during payment authorization and staff access workflows.

Support
Targets (9)

Supported targets

Anchor to PropertiesProperties

Configure the following properties on the PinPad component.

Anchor to onSubmit
onSubmit
(pin: number[]) => Promise<>
required

A callback function executed when the PIN is submitted, receiving the PIN as an array of numbers. Must return a Promise that resolves to either 'accept' or 'reject' to indicate validation success or failure.

Anchor to label
label
string

The content for the prompt displayed on the pin pad that instructs users what to enter.

Anchor to masked
masked
boolean

A boolean that determines whether the entered PIN should be masked with dots or asterisks to protect privacy and security.

Anchor to maxPinLength
maxPinLength

The maximum length of the PIN that users can enter, constraining the number of digits.

Anchor to minPinLength
minPinLength

The minimum length of the PIN that users must enter before submission is allowed.

Anchor to onPinEntry
onPinEntry
(pin: number[]) => void

A callback function executed when a PIN is entered, receiving the PIN as an array of numbers. Use this for real-time feedback or validation during PIN entry.

Anchor to pinPadAction
pinPadAction

A call-to-action configuration displayed between the entry view and the keypad, consisting of a label and function that returns the current PIN.

Anchor to ExamplesExamples

Anchor to Validate a PIN securelyValidate a PIN securely

Collect and validate PINs securely using a numeric keypad interface. This example demonstrates a PinPad with an onPinSubmit callback that validates entered PINs asynchronously. The validation function receives an array of numbers representing the entered digits and returns a Promise that resolves to PinValidationResult (either "accept" or "reject"). In this example, the validation simulates a 1-second async check against a test PIN sequence [1, 2, 3, 4, 5, 6]. The component masks digits for security, provides haptic feedback, and supports error states for invalid PINs—ideal for payment authorization or staff access workflows.

Validate a PIN securely

Collect and validate PINs securely using a numeric keypad interface. This example demonstrates a PinPad with an `onPinSubmit` callback that validates entered PINs asynchronously. The validation function receives an array of numbers representing the entered digits and returns a Promise that resolves to `PinValidationResult` (either `'accept'` or `'reject'`). In this example, the validation simulates a 1-second async check against a test PIN sequence [1, 2, 3, 4, 5, 6]. The component masks digits for security, provides haptic feedback, and supports error states for invalid PINs—ideal for payment authorization or staff access workflows.

Validate a PIN securely

const onPinSubmit = (pin: number[]): Promise<PinValidationResult> => {
return new Promise((resolve) => {
setTimeout(() => {
const isPinValid =
pin.length === 6 && pin.every((digit, index) => digit === index + 1);
const result: PinValidationResult = isPinValid ? 'accept' : 'reject';
resolve(result);
}, 1000);
});
};

Anchor to Best practicesBest practices

  • Mask sensitive entry: Set masked to true for security-related PIN entry to prevent shoulder-surfing.
  • Set appropriate constraints: Define minPinLength and maxPinLength based on security needs (4-6 for basic, 6-10 for higher security).
  • Validate securely on backend: Use onSubmit for server-side verification. Return accept or reject. Implement rate limiting.
  • Write clear labels: Use direct prompts like "Enter Manager PIN" rather than verbose text.
  • Use PIN terminology: Always use "PIN" in all capitals.

Anchor to LimitationsLimitations

  • PinPad is designed for numeric PIN entry only—alphanumeric passcodes or complex passwords require different input components.
  • PIN length is constrained to 4-10 digits—requirements outside this range need alternative authentication methods.
  • The component provides the keypad interface and basic validation—additional security measures like rate limiting, attempt tracking, or lockout mechanisms must be implemented in your onSubmit callback.
Was this page helpful?