passage-elements

Getting Started

Install this package using npm.

npm i --save @passageidentity/passage-elements

This package includes four custom elements: passage-auth, passage-login, passage-register, passage-profile, and passage-passkey-table.

• passage-auth is a single element that handles both login and registration of users.
• passage-login and passage-register split out the login and register operations into separate elements. These elements should be used when your login and registration functionality are on different pages.
• passage-profile is an element that allows users to manage their stored profile information. The profile element provides a UI for users to view and edit their account data and perform actions such as updating their email or adding a device to their account.
• passage-passkey-table is an element that renders a table of passkeys associated with the current user. This table is used within the <passage-profile> element and is often used standalone in situations where you want users to have passkey management but not identifier management capabilities. The table can view, edit, add, and revoke passkeys from the user's account.

Using a Passage Custom Element

Import the custom elements in your JavaScript/TypeScript module:

import '@passageidentity/passage-elements/passage-auth'

import '@passageidentity/passage-elements/passage-login'

import '@passageidentity/passage-elements/passage-register'

import '@passageidentity/passage-elements/passage-profile'

import '@passageidentity/passage-elements/passage-passkey-table'

This import will register just the associated custom elements which can then be used as HTML tags like:

<passage-auth app-id="<PASSAGE_APP_ID"></passage-auth>

<passage-login app-id="<PASSAGE_APP_ID"></passage-login>

<passage-register app-id="<PASSAGE_APP_ID"></passage-register>

<passage-profile app-id="<PASSAGE_APP_ID"></passage-profile>

<passage-passkey-table app-id="<PASSAGE_APP_ID"></passage-passkey-table>

UI Customization with CSS Variables

The passage-auth, passage-login, passage-register, and passage-profile elements can be customized by utilizing CSS variables on the host webpage. All available variables, along with their default values, are shown below.

/* Default values shown */

passage-auth,
passage-login,
passage-register {
    /* Passage Container Styles */
    --passage-container-background: transparent;
    --passage-container-max-width: 220px;
    --passage-container-margin: auto;
    --passage-container-padding: 30px 30px 20px;
    --passage-error-color: #ff0000;

    /* Body Font Styles */
    --passage-body-font-family: 'DM Sans', BlinkMacSystemFont, -apple-system, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell',
        'Fira Sans', 'Droid Sans', 'Helvetica Neue', 'Helvetica', 'Arial', sans-serif;
    --passage-body-font-size: 14px;
    --passage-body-font-weight: 400;
    --passage-body-text-color: #000; /* text color for main body text and icons */

    /* Header Font Styles */
    --passage-header-font-family: 'DM Sans', BlinkMacSystemFont, -apple-system, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu',
        'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', 'Helvetica', 'Arial', sans-serif;
    --passage-header-font-weight: 700;
    --passage-header-text-color: #000;
    --passage-header-font-size: 24px;

    /* Button Styles */
    --passage-button-font-size: 16px;
    --passage-button-font-weight: 400;
    --passage-button-width: 50%;
    --passage-button-border-radius: 75px;

    /* Color Palette */
    --passage-onprimary-color: #fff; /* text color on primary control background */
    --passage-primary-color: #000; /* main color used for controls */

    --passage-onhover-color: #fff;
    --passage-hover-color: #4d4d4d;

    --passage-onactive-color: #fff;
    --passage-active-color: #6b6b6b;

    /* Email and Phone Input Box Styles */
    --passage-control-border-radius: 5px;
    --passage-control-border-color: #dbdbdb;
}

passage-profile,
passage-passkey-table {
    /* All passage-auth styles from above still apply */

    /* Table Styles */
    --passage-table-header-border-color: #d7d7d7;
    --passage-table-row-hover-color: #e0e0e0;
    --passage-table-row-border-color: #e8e8e8;
    --passage-table-paginator-selected-color: #d7d7d7;
    --passage-table-paginator-hover-color: #e8e8e8;
}

To utilize one or more CSS variables, the user only needs to add the variable declarations inside of a style block that will be loaded onto the page. The user may choose to scope the CSS variables in one of two ways:

/* Apply rules to individual elements */
passage-auth {
    --passage-container-max-width: 220px;
    /* ... more variables ... */
}

passage-profile {
    --passage-container-max-width: 400px;
}

/* Globally apply rules to all passage elements (auth, login, register, and profile) */
:root {
    --passage-primary-color: #000;
    /* ... more variables ... */
}

UI Customization with CSS Parts

Deeper customization that goes beyond simple styling allowed by the CSS variables is possible using CSS part selectors. The elements have two stylable parts - the buttons and the text input fields. Using the CSS ::part() selectors deep CSS customization of the text fields and buttons in the elements is possible, including many common psuedo-classes.

passage-auth::part(input) {
    border-color: #dbdbdb;
}
passage-auth::part(input):focus {
    border-color: #000000;
}

passage-auth::part(button) {
    border: 1px solid transparent;
}
passage-auth::part(button):hover {
    border: 1px solid blue;
}

Styling the Profile Table

The <passage-profile> and <passage-passkey-table> elements contain a table that can be deeply styled using CSS parts. The table is a standard HTML table and each component has a specific CSS part that can be used to style that element of the HTML table. The full list of supported parts are:

::part(passage-table) // The root <table> element
::part(passage-table-header-row) // <tr> for header row
::part(passage-table-header-cell) // <th> for header row
::part(passage-table-row) // <tr>
::part(passage-table-cell) // <td>
::part(passage-table-expansion-row) // <tr> for expanded row
::part(paginator-button) // the <div> element for each button in the paginator