Headless components rendering reference

Purpose

Headless integration enables the SDK to provide a framework for managing the login session and flow control, while allowing for complete customizability in the rendering and implementation of the login components.

Using the component descriptor structure documented below, you can implement its visual and functional components accordingly.

📘

In minimal response mode, rendering-related data (layout, branding, and forms[].widgets[].render) is not included.

📘

Headless example applications use the minimal response representation by default.

Screens

The screen object represents the current logical step in the login/registration flow (for example, identification, password, registration, etc.).

Forms/widgets

The forms array contains one or more form definitions. Each form is composed of widgets, which are the atomic building blocks of a UI presentation.

Each widget has an identifier id and a type attribute. Based on the type attribute, the following different widgets are defined.

static

A widget that contains static text or HTML for display on a form.

Attributes specific to static widget:

• value: string: content to be displayed

Example:

{
  "type": "static",
  "id": "section-title",
  "value": "Sign in"
  }
}

input

A widget that is used for customer data input.

Attributes specific to input widget:

• label: string: label of the input field
• value: string: value of the input field
• readonly: boolean
• autocomplete: string
• inputmode: string
• validator: object
  • minLength: number
  • maxLength: number
  • regexp: string
  • required: boolean

Example:

{
  "type": "input",
  "id": "email",
  "label": "Email",
  "value": null,
  "readonly": false,
  "autocomplete": "username",
  "inputmode": "email",
  "validator": {
    "minLength": null,
    "maxLength": null,
    "regex": null,
    "required": true
  }
}

password

A widget that is used for password input.

Attributes specific to password widget:

• label: string: label of the password field
• qualityIndicator: boolean
• validator: object
  • minLength: number
  • maxLength: number
  • maxNumericCharacterSequences: number
  • maxRepeatedCharacters: number
  • mustContain: Array<UPPERCASE|LOWERCASE|NUMERIC|SPECIAL>
  • restrictedCharacters: string

Example:

{
  "type": "password",
  "id": "password",
  "label": "Enter your password",
  "qualityIndicator": false,
  "validator": null
}

passcode

A widget dedicated to MFA passcode input.

Attributes specific to the passcode widget:

• id: string
• label: string: label of the passcode field
• validator
  • length

Example:

{
  "type": "passcode",
  "id": "passcode",
  "label": "6-digit passcode",
  "validator": {
    "length": 6
  }
}

phone

A widget that is used for phone input.

Attributes specific to the phone widget:

• id: string
• label: string: label of the phone field
• readonly: boolean
• value: string
• validator
  • required: boolean

Example:

{
  "type": "phone",
  "id": "phone",
  "label": "Telephone number",
  "value": "+36303411289",
  "readonly": false,
  "validator": {
    "required": true
  }
}

date

A widget that is used for date input.

Attributes specific to the date widget:

• id: string
• label: string: label of the date field
• readonly: boolean
• value: string
• render
  • type: native|fieldSet
• validator
  • notBefore: string
  • notAfter: string
  • required: boolean

Example:

{
  "type": "date",
  "id": "dob",
  "label": "Date of birth",
  "value": "2000-01-01",
  "readonly": false,
  "validator": null
}

select

A widget that is used to receive input from a predefined set of values.

Attributes specific to the select widget:

• id: string
• label: string
• readonly: boolean
• value: string
• options: Array\< { value: string, label: string, type: item } || { label: string, type: group, options: [{ { value: string, label: string, type: item }… }] }
• validator
  • required: boolean

Example:

{
  "type": "select",
  "id": "environment",
  "label": "Environment",
  "value": "dev",
  "readonly": false,
  "options": [
    {
      "value": "dev",
      "label": "Development"
    },
    {
      "value": "prod",
      "label": "Production"
    }
  ],
  "validator": {
    "required": true
  }
}

multiSelect

A widget that is used to receive inputs from a predefined set of values.

Attributes specific to the multiSelect widget:

• id: string
• label: string
• readonly: boolean
• value: Array<string>
• options: Array\< { value: string, label: string, type: item } || { label: string, type: group, options: [{ { value: string, label: string, type: item }… }] }
• validator
  • minSelectable: number
  • maxSelectable: number

Example:

{
  "type": "multiSelect",
  "id": "environment",
  "label": "Environment",
  "value": [
    "dev",
    "prod"
  ],
  "readonly": false,
  "options": [
    {
      "value": "dev",
      "label": "Development"
    },
    {
      "value": "prod",
      "label": "Production"
    }
  ],
  "validator": {
    "minSelectable": 1,
    "maxSelectable": 2
  }
}

checkbox

A widget which is used for customer data input and can be either true or false.

Attributes specific to the checkbox widget:

• id: string
• label: string
• readonly: boolean
• value: boolean
• validator
  • required: boolean

Example:

{
  "type": "checkbox",
  "id": "rememberDevice",
  "label": "Remember this device for 30 days",
  "readonly": false,
  "value": true,
  "validator": {
    "required": false
  }
}

submit

A widget that is used to submit a form.

Attributes specific to the submit widget:

• id: string
• picture: reference
• label: string

Example:

{
  "type": "submit",
  "id": "submit",
  "label": "Resend"
  }
}

Rendering reference extended responses

📘

If you need the extended response, you can disable the SDK’s minimal response mode to retrieve the full representation instead.

The following reference outlines the additional fields and rendering information included in extended responses.

Layout

The layout object defines how widgets from different forms should be arranged on the screen. It supports vertical and horizontal grouping, allowing for flexible UI composition.

Forms with render

static with render

• render: object
  • type: (text|html)

{
  "type": "static",
  "id": "section-title",
  "value": "Sign in",
  "render": {
    "type": "text"
  }
}

date with render

• render
  • type: native|fieldSet

{
  "type": "date",
  "id": "dob",
  "label": "Date of birth",
  "value": "2000-01-01",
  "readonly": false,
  "render": {
    "type": "native"
  },
  "validator": null
}

select with render

• render
  • type: dropdown|radio

{
  "type": "select",
  "id": "environment",
  "label": "Environment",
  "value": "dev",
  "readonly": false,
  "render": {
    "type": "dropdown"
  },
  "options": [
    {
      "value": "dev",
      "label": "Development"
    },
    {
      "value": "prod",
      "label": "Production"
    }
  ],
  "validator": {
    "required": true
  }
}

checkbox with render

• render
  • type: (checkboxHidden|checkboxShown)
  • labelType: (text|html)

{
  "type": "checkbox",
  "id": "rememberDevice",
  "label": "Remember this device for 30 days",
  "readonly": false,
  "value": true,
  "validator": {
    "required": false
  },
  "render": {
    "type": "checkboxShown",
    "labelType": "text"
  }
}

submit with render

• render
  • type: button|link|any
  • textColor: string
  • bgColor: string
  • hint
    • icon: string
    • variant: string

{
  "type": "submit",
  "id": "submit",
  "label": "Resend",
  "render": {
    "type": "link",
    "hint": {
      "icon": null,
      "variant": "primary"
    },
    "textColor": null,
    "bgColor": null
  }
}