@molecule/app-join-code-react

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

React multi-slot join-code input.

Exports:

• <JoinCode> — N-slot single-character input with auto-advance, paste-to-fill, alphabet validation, and onComplete notification.
• JoinCodeProps, JoinCodeAlphabet — public types.

Companion locale bond: @molecule/app-locales-join-code.

Quick Start

import { JoinCode } from '@molecule/app-join-code-react'

;<JoinCode
  length={6}
  alphabet="alphanumeric"
  onChange={(code) => setCode(code)}
  onComplete={(code) => verifyCode(code)}
/>

Type

feature

Installation

npm install @molecule/app-join-code-react @molecule/app-i18n @molecule/app-react @molecule/app-ui react
npm install -D @types/react

API

Interfaces

JoinCodeProps

Props for the <JoinCode> component.

interface JoinCodeProps {
  /** Number of slots / characters in the code. Defaults to `6`. */
  length?: number
  /**
   * Controlled value. When provided, the component is controlled and ignores
   * `defaultValue`. The value may be shorter than `length`; missing slots
   * render empty.
   */
  value?: string
  /**
   * Initial value when uncontrolled. Ignored when `value` is provided.
   */
  defaultValue?: string
  /**
   * Called whenever the code changes (typing, paste, backspace).
   * The argument is the *current* code (may be shorter than `length`).
   */
  onChange?: (code: string) => void
  /**
   * Called when the code reaches the configured `length` and every character
   * passes alphabet validation. Fires once per completion (re-fires when the
   * code is cleared and re-completed).
   */
  onComplete?: (code: string) => void
  /**
   * Whether to fire `onComplete` automatically when `length` is reached.
   * Defaults to `true`.
   */
  autoSubmit?: boolean
  /** Allowed character set. Defaults to `'alphanumeric'`. */
  alphabet?: JoinCodeAlphabet
  /** Whether the input is disabled. */
  disabled?: boolean
  /** Optional className applied to the outer wrapper. */
  className?: string
}

Types

JoinCodeAlphabet

Alphabet a join code may use.

• 'numeric' — 0-9 only.
• 'letters' — A-Z only (case-insensitive on input, normalised to upper-case).
• 'alphanumeric' — A-Z + 0-9 (case-insensitive, normalised to upper-case).

type JoinCodeAlphabet = 'numeric' | 'letters' | 'alphanumeric'

Functions

JoinCode(props)

Multi-slot join-code input. Renders one single-character <input> per slot with auto-advance focus, backspace-to-previous, and paste-to-fill behaviour.

• Controlled when value is provided; the parent must update it via onChange. The displayed code is clamped to length characters.
• Uncontrolled otherwise; defaultValue seeds the initial state.

Calls onComplete(code) once the code reaches length characters and every character matches alphabet. The fire is suppressed while autoSubmit is false.

All user-visible text (label, slot aria-labels) flows through t() so apps can localise via the companion @molecule/app-locales-join-code bond.

Styling is delegated to getClassMap() — no Tailwind utility strings live in this package.

function JoinCode(props: JoinCodeProps): ReactElement<unknown, string | JSXElementConstructor<any>>

• props — See JoinCodeProps.

Returns: The rendered join-code input.

Injection Notes

Requirements

Peer dependencies:

• @molecule/app-i18n ^1.0.1
• @molecule/app-react ^1.0.1
• @molecule/app-ui ^1.0.1
• react ^18.0.0 || ^19.0.0

Runtime Dependencies

• @molecule/app-i18n
• @molecule/app-react
• @molecule/app-ui
• react

Translations

Translation strings are provided by @molecule/app-locales-join-code.