Customize appearance of Hanko Elements

This guide will walk you through the UI customization of Hanko Elements components.

Hanko Elements Appearance Customization Guide:

About Hanko:

Hanko is a modern open source authentication solution and the fastest way you integrate passkeys, 2FA, SSO, and more—with full control over your data. Move between self-hosted and Hanko Cloud anytime. No lock-in. Just Auth how it should be: secure, user friendly, and fully yours.

What This Guide Covers: This guide demonstrates how to customize the visual appearance of Hanko web components (<hanko-auth>, <hanko-profile>, <hanko-login>, and <hanko-registration>) to match your application’s design and branding. You’ll learn to use CSS variables and CSS Shadow Parts to create a cohesive user interface that aligns with your application’s style.

Key Technologies:

• Hanko Elements
• CSS variables
• CSS Shadow Parts
• Web Components Shadow DOM
• CSS styling
• Responsive design
• Frontend theming techniques

Prerequisites:

• Basic knowledge of CSS styling, web components, and frontend development
• Understanding of CSS variables and Shadow DOM concepts will be helpful

Tasks You’ll Complete:

• Configure CSS variables to customize colors, fonts, and layout
• Use CSS Shadow Parts to target specific component elements
• Implement custom styling for different component states
• Create responsive designs that work across devices
• Apply consistent branding across all Hanko components
• Learn advanced styling techniques for web component customization

CSS variables

You can use CSS variables to customize the appearance of hanko-auth and hanko-profile elements to match your design requirements. The complete list of available CSS variables and their default values is shown below:

hanko-auth,
hanko-profile {
  /* Color Scheme */
  --color: #333333;
  --color-shade-1: #8f9095;
  --color-shade-2: #e5e6ef;

  --brand-color: #506cf0;
  --brand-color-shade-1: #6b84fb;
  --brand-contrast-color: white;

  --background-color: white;
  --error-color: #e82020;
  --link-color: #506cf0;

  /* Font Styles */
  --font-weight: 400;
  --font-size: 16px;
  --font-family: sans-serif;

  /* Border Styles */
  --border-radius: 8px;
  --border-style: solid;
  --border-width: 1px;

  /* Item Styles */
  --item-height: 34px;
  --item-margin: 0.5rem 0;

  /* Container Styles */
  --container-padding: 30px;
  --container-max-width: 410px;

  /* Headline Styles */
  --headline1-font-size: 24px;
  --headline1-font-weight: 600;
  --headline1-margin: 0 0 1rem;

  --headline2-font-size: 16px;
  --headline2-font-weight: 600;
  --headline2-margin: 1rem 0 0.5rem;

  /* Divider Styles */
  --divider-padding: 0 42px;
  --divider-visibility: visible;

  /* Link Styles */
  --link-text-decoration: none;
  --link-text-decoration-hover: underline;

  /* Input Styles */
  --input-min-width: 14em;

  /* Button Styles */
  --button-min-width: max-content;
}

CSS Shadow Parts

In addition to CSS variables, you can use the ::part selector to customize specific elements within the components.

Note that shadow parts only work when the web components are attached to the shadow DOM, which is the default behavior. You can enable the shadow DOM for the components using the following code:

register("https://hanko.yourdomain.com", { shadow: true });

// equals
register("https://hanko.yourdomain.com");

Name	Description
container	the UI container
headline1	the “h1” headlines
headline2	the “h2” headlines
paragraph	the paragraph elements
button	every button element
primary-button	the primary button
secondary-button	the secondary button on the email login page
input	every input field
text-input	every input field not used for passcodes
passcode-input	the passcode input fields
link	the links in the footer section
error	the error message container
error-text	the error message
divider	the horizontal divider on the login page
divider-text	the divider text
divider-line	the line before and after the divider-text
form-item	the container of a form item, e.g. an input field or a button

Examples

The following examples show how to apply custom styles to specific shadow parts:

Stacking hanko-auth component fields vertically

This example demonstrates how to force the input fields and buttons within the hanko-auth component to stack vertically. The ::part(form-item) selector targets the form-item shadow part within the hanko-auth component, which is applied using the tag name.

<style>
  hanko-auth::part(form-item) {
    /* Force the input fields and buttons are on top of each other */
    min-width: 100%;
  }
</style>
<hanko-auth></hanko-auth>

Modifying the main headlines for Hanko components

This example shows how to adjust the main headlines for all hanko components by targeting the headline1 shadow part. The .hankoComponent::part(headline1) selector applies the styles to the headline1 shadow part within elements that have the hankoComponent class.

<style>
  .hankoComponent::part(headline1) {
    /* Adjust the main headlines for all hanko components */
    font-size: 1.3em;
    font-weight: 400;
  }
</style>

<hanko-auth class="hankoComponent"></hanko-auth>
<hanko-profile class="hankoComponent"></hanko-profile>

Applying box shadow on button of hanko-auth component

In this example, a box shadow is applied to the button shadow part of the hanko-auth component when hovering over it. The #hankoAuth::part(button):hover selector targets the button shadow part within the hanko-auth component using the ID selector #hankoAuth and applies the styles when the :hover pseudo-class is active.

<style>
  #hankoAuth::part(button):hover {
    box-shadow: 3px 3px 2px #888;
  }
</style>

<hanko-auth id="hankoAuth"></hanko-auth>

For more examples and design inspiration, check out our blog post, Make Hanko Components Shine.