Passcode

<quiet-passcode>

stable

since 1.0

Passcodes let users enter fixed-length passcodes, verification tokens, one-time codes, and similar data in a user-friendly way.

<quiet-passcode 
  name="code"
  label="Authorization code"
  description="Open your authenticator app to get the code."
  format="### ###"
></quiet-passcode>

Examples Jump to heading

Labels and descriptions Jump to heading

You can use the label and description attributes to provide plain text labels and descriptions for the passcode. If you want to provide HTML, use the label and description slots instead.

If you can't access the code, you can reset your account.

<quiet-passcode name="code" label="Verification code">
  <span slot="description">
    If you can't access the code, you can <a href="https://example.com/" target="_blank">reset your account</a>.
  </span>
</quiet-passcode>

Providing an initial value Jump to heading

Use the value attribute to provide an initial value for the passcode field.

<quiet-passcode name="code" label="Verify PIN" value="5309"></quiet-passcode>

Changing the input type Jump to heading

By default, only numbers are allowed in passcodes. To change this, set the type attribute to alpha, alphanumeric, or any to allow all characters. The component's inputmode will be set automatically based on the type.

<quiet-passcode label="Letters only" type="alpha"></quiet-passcode><br>
<quiet-passcode label="Letters and numbers" type="alphanumeric"></quiet-passcode><br>
<quiet-passcode label="Any character" type="any"></quiet-passcode>

Changing the format Jump to heading

The format attribute dictates how many characters are allowed and where delimiters are shown. Use # to represent an allowed character. Use space, dash, or any other character to show a delimiter. Delimiters will not be included in the submitted value.

<quiet-passcode label="Verification code" format="### ###" name="code"></quiet-passcode><br>
<quiet-passcode label="Super secret code" format="##–####" name="code"></quiet-passcode>

Case sensitivity Jump to heading

For alpha and alphanumeric passcodes, the value is shown in uppercase letters by default. To allow case sensitivity, add the case-sensitive attribute. In both cases, the value will be submitted as it was entered by the user.

<quiet-passcode 
  label="Case sensitive"
  type="alphanumeric"
  format="######"
  case-sensitive
></quiet-passcode>

Masking the value Jump to heading

Add the masked attribute to prevent the value from being shown on screen.

<quiet-passcode label="Masked" masked value="1234"></quiet-passcode>

Filled and unstyled passcodes Jump to heading

Set the appearance attribute to normal, filled, or unstyled to change the passcode's appearance.

<quiet-passcode appearance="normal" label="Normal passcode"></quiet-passcode><br>
<quiet-passcode appearance="filled" label="Filled passcode"></quiet-passcode><br>
<quiet-passcode appearance="unstyled" label="Unstyled passcode"></quiet-passcode>

Changing the size Jump to heading

Use the size attribute to change the passcode's size.

<quiet-passcode size="xs" label="Extra small"></quiet-passcode><br>
<quiet-passcode size="sm" label="Small"></quiet-passcode><br>
<quiet-passcode size="md" label="Medium"></quiet-passcode><br>
<quiet-passcode size="lg" label="Large"></quiet-passcode><br>
<quiet-passcode size="xl" label="Extra large"></quiet-passcode>

Disabling Jump to heading

Use the disabled attribute to disable the passcode.

<quiet-passcode label="Disabled" disabled></quiet-passcode>

Validation Jump to heading

A couple attributes can be used to enable validation using the Constraint Validation API. These include required and pattern. They work exactly like their native counterparts.

              
                Submit
                Reset

<form action="about:blank" method="get" target="_blank">
  <quiet-passcode 
    name="required" 
    label="Required" 
    description="The code must be filled in completely."
    required
  ></quiet-passcode><br>
  <quiet-passcode 
    name="pattern" 
    label="Pattern" 
    description="The code must start with a letter and end with numbers."
    type="alphanumeric" 
    required 
    pattern="[A-Za-z]{1}[0-9]{3}" 
    format="#–###"
  ></quiet-passcode><br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
  <quiet-button type="reset">Reset</quiet-button>
</form>

passcodes are fixed-length, so setting required will ensure that the field is not empty and contains the correct number of characters before submitting.

Using custom validation Jump to heading

Use the custom-validity attribute to make the passcode invalid and show a custom error message on submit. This will override all other validation parameters. To clear the error, remove the attribute or set it to an empty string.

<form action="about:blank" method="get" target="_blank">
  <quiet-passcode
    name="code"
    label="Authorization code"
    description="This field will be invalid until the custom-validity attribute is removed"
    custom-validity="Not so fast, bubba!"
  ></quiet-passcode>
  <br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
</form>

Most validation attributes work exactly like their native counterparts. However, the custom-validity attribute is offered in lieu of the setCustomValidity() method. This allows you to declaratively set custom errors instead of having to call a method with JavaScript.

Styling validation Jump to heading

You can style valid and invalid passcodes using the :valid and :invalid pseudo classes.

              
                Submit
                Reset

<form action="about:blank" method="get" target="_blank" class="passcode__validation-pseudo">
  <quiet-passcode
    name="name"
    label="Authorization code"
    description="This field is required"
    required
  ></quiet-passcode>
  <br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
  <quiet-button type="reset">Reset</quiet-button>
</form>

<style>
  .passcode__validation-pseudo {
    quiet-passcode:valid {
      outline: solid 2px var(--quiet-constructive-stroke-mid);
      outline-offset: .5rem;
    }

    quiet-passcode:invalid {
      outline: solid 2px var(--quiet-destructive-stroke-mid);
      outline-offset: .5rem;
    }
  }
</style>

However, these selectors will match even before the user has had a chance to fill out the form. More often than not, you'll want to use the user-valid and user-invalid custom states instead. This way, validation styles are only shown after the user interacts with the form control or when the form is submitted.

              
                Submit
                Reset

<form action="about:blank" method="get" target="_blank" class="passcode__validation-custom">
  <quiet-passcode
    name="name"
    label="Authorization code"
    description="This field is required"
    required
  ></quiet-passcode>
  <br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
  <quiet-button type="reset">Reset</quiet-button>
</form>

<style>
  .passcode__validation-custom {
    quiet-passcode:state(user-valid) {
      outline: solid 2px var(--quiet-constructive-stroke-mid);
      outline-offset: .5rem;
    }

    quiet-passcode:state(user-invalid) {
      outline: solid 2px var(--quiet-destructive-stroke-mid);
      outline-offset: .5rem;
    }
  }
</style>

Styling passcodes Jump to heading

Passcodes are styled like form controls for consistency, but feel free to customize them to your liking. Here's an example using a card and some custom CSS.

Submit

<quiet-card class="passcode__centered">
  <quiet-passcode 
    name="code"
    label="Access code"
    description="Enter the code we just texted you."
    format="### ###"
    class=""
  ></quiet-passcode>
  <quiet-button variant="primary">Submit</quiet-button>
</quiet-card>

<style>
  quiet-card.passcode__centered {
    max-width: 360px;
    margin-inline: auto;

    &::part(body) {
      padding: 2.5rem 3rem 3rem 3rem;
    }

    quiet-passcode {
      text-align: center;
      margin-block-end: 3rem;

      &::part(label) {
        max-width: none;
        font-size: 2rem;
      }

      &::part(description) {
        margin-block-end: 2rem;
      }

      &::part(visual-box) {
        margin-inline: auto;
      }
    }

    quiet-button {
      width: 100%;
    }
  }
</style>

API Jump to heading

Importing Jump to heading

The autoloader is the recommended way to import components but, if you prefer to do it manually, the following code snippets will be helpful.

CDN

npm

To manually import <quiet-passcode> from the CDN, use the following code.

import 'https://cdn.jsdelivr.net/npm/@quietui/quiet@1.0.0/dist/components/passcode/passcode.js';

To manually import <quiet-passcode> from npm, use the following code.

import '@quietui/quiet/dist/components/passcode/passcode.js';

Slots Jump to heading

Passcode supports the following slots. Learn more about using slots

Name	Description
`label`	The passcode's label. For plain-text labels, you can use the `label` attribute instead.
`description`	The passcode's description. For plain-text descriptions, you can use the `description` attribute instead.

Properties Jump to heading

Passcode has the following properties that can be set with corresponding attributes. In many cases, the attribute's name is the same as the property's name. If an attribute is different, it will be displayed after the property. Learn more about attributes and properties

Property / Attribute	Description	Type	Default
`associatedForm`	A reference to the `<form>` associated with the form control, or `null` if no form is associated.	`HTMLFormElement null`	`null`
`label`	The passcode's label. If you need to provide HTML in the label, use the `label` slot instead.	`string`
`description`	The passcode's description. If you need to provide HTML in the description, use the `description` slot instead.	`string`
`name`	The name of the passcode. This will be submitted with the form as a name/value pair.	`string`
`value`	The passcode's value.	`string`	`''`
`format`	The format of the passcode. This dictates the number of characters and where delimiters will show. Use `#` to represent an allowed character. Use a space, dash, or any other character to represent a delimiter. Delimiters are shown for visual clarity, but won't be included in the submitted value.	`string`	`'####'`
`disabled`	Disables the passcode.	`boolean`	`false`
`appearance`	The type of passcode to render.	`'normal' 'filled' 'unstyled'`	`'normal'`
`size`	The passcode's size.	`'xs' 'sm' 'md' 'lg' 'xl'`	`'md'`
`masked`	Masks the characters so they're not displayed on screen.=.	`boolean`	`false`
`type`	The type of characters to allow in the input.	`'numeric' 'alpha' 'alphanumeric' 'any'`	`'numeric'`
`caseSensitive` `case-sensitive`	Makes the passcode case sensitive.	`boolean`	`false`
`form`	The form to associate this control with. If omitted, the closest containing `<form>` will be used. The value of this attribute must be an ID of a form in the same document or shadow root.	`string`
`required`	Makes the passcode required. Form submission will not be allowed when this is set and the passcode is blank.	`boolean`	`false`
`pattern`	A regular expression the value should match to be considered valid.	`string`
`customValidity` `custom-validity`	You can provide a custom error message to force the passcode to be invalid. To clear the error, set this to an empty string.	`string`	`''`
`autocomplete`	Tells the browser how to autocomplete the passcode. See this page for available values.	`string`	`'one-time-code'`
`autofocus`	Tells the browser to focus the passcode when the page loads or a dialog is shown.	`boolean`
`enterkeyhint`	Sets the enter key label on virtual keyboards.	`'enter' 'done' 'go' 'next' 'previous' 'search' 'send'`

Methods Jump to heading

Passcode supports the following methods. You can obtain a reference to the element and call them like functions in JavaScript. Learn more about methods

Name	Description	Arguments
`focus()`	Sets focus to the passcode.
`blur()`	Removes focus from the passcode.
`checkValidity()`	Checks if the form control has any restraints and whether it satisfies them. If invalid, `false` will be returned and the `invalid` event will be dispatched. If valid, `true` will be returned.
`reportValidity()`	Checks if the form control has any restraints and whether it satisfies them. If invalid, `false` will be returned and the `invalid` event will be dispatched. In addition, the problem will be reported to the user. If valid, `true` will be returned.

Events Jump to heading

Passcode dispatches the following custom events. You can listen to them the same way was native events. Learn more about custom events

Name	Description
`input`
`change`
`quiet-blur`	Emitted when the passcode loses focus. This event does not bubble.
`quiet-change`	Emitted when the user commits changes to the passcode's value.
`quiet-focus`	Emitted when the passcode receives focus. This event does not bubble.
`quiet-input`	Emitted when the passcode receives input.
`quiet-input-complete`	Emitted when the final character in the passcode is entered.

CSS parts Jump to heading

Passcode exposes internal elements that can be styled with CSS using the selectors shown below. Learn more about CSS parts

Name	Description	CSS selector
`label`	The element that contains the passcode's label.	`::part(label)`
`description`	The element that contains the passcode's description.	`::part(description)`
`visual-box`	The element that wraps the characters, delimiters, and the hidden input.	`::part(visual-box)`
`character-box`	Each individual character box.	`::part(character-box)`
`delimiter`	Each individual delimiter.	`::part(delimiter)`

Custom States Jump to heading

Passcode has the following custom states. You can target them with CSS using the selectors shown below. Learn more about custom states

Name	Description	CSS selector
`disabled`	Applied when the passcode is disabled.	`:state(disabled)`
`blank`	Applied when the passcode has a blank value.	`:state(blank)`
`focused`	Applied when the passcode has focus.	`:state(focused)`
`user-valid`	Applied when the passcode is valid and the user has sufficiently interacted with it.	`:state(user-valid)`
`user-invalid`	Applied when the passcode is invalid and the user has sufficiently interacted with it.	`:state(user-invalid)`

Passcode

Examples Jump to heading #

Labels and descriptions Jump to heading #

Providing an initial value Jump to heading #

Changing the input type Jump to heading #

Changing the format Jump to heading #

Case sensitivity Jump to heading #

Masking the value Jump to heading #

Filled and unstyled passcodes Jump to heading #

Changing the size Jump to heading #

Disabling Jump to heading #

Validation Jump to heading #

Using custom validation Jump to heading #

Styling validation Jump to heading #

Styling passcodes Jump to heading #

API Jump to heading #

Importing Jump to heading #

Slots Jump to heading #

Properties Jump to heading #

Methods Jump to heading #

Events Jump to heading #

CSS parts Jump to heading #

Custom States Jump to heading #