@onlive.ai/flow

A package containing reusable web components for building multi-step flows with forms, actions, and stages.

Installation

npm install @onlive.ai/flow

Workflow

The Onlive Flow package is designed to facilitate the creation of interactive flows with multiple steps, forms, and actions. It provides a set of components that can be easily integrated into your web applications.

Its uses the Onlive Flow Client to manage the flow process, including data handling, navigation, and state management.

Components

Onlive Flow provides several components to help you build interactive flows. You can use the main ofl-flow component to create a complete flow, or use the individual components to customize your flow.

The following image shows the structural distribution of the components:

Flow components Form components

OFL-Flow

Description

The main container component that manages a flow process with multiple steps, forms, actions, and navigation between stages. It coordinates with a FlowClient to handle data and navigation logic.

This component already includes the ofl-stages, ofl-form, and ofl-actions components, so you can use it as a complete solution for your flow.

Also includes the Onlive Flow Client, which is used to manage the flow process.

Importing

// ESM/Bundler Import
import "@onlive.site/flow/components/flow/flow.js";

// Script Import (CDN)
<script
  type="module"
  src="https://cdn.onlive.site/@onlive.site/flow@latest/components/flow/flow.js"
></script>;

Then use the component in your HTML:

<ofl-flow
  .context=${{
    options: {
      baseUrl: "https://flow-api.onlive.site",
      organizationId: "58b4b948-36d7-459b-adea-ca60412725a6"
      flowId: "683dbe2ea5ab95720a6b242f",
      customStyles: customStyleSheet,
      initialState: {},
      tracking: true,
      navigation: "default",
      inContainer: false
    }
  }}
></ofl-flow>

Properties

Name	Type	Description	Reflects	Default Value
`context`	`PackageContext`	Package context containing flow configuration	`false`	`undefined`

Events

Name	Description	Event Detail
`ofl-change`	Fired when form field values change	`{ detail: { values: Record<string, FieldValue>, valid: boolean } }`
`ofl-action-click`	Fired when an action button is clicked	`{ detail: { action: Action } }`
`ofl-organization-call`	Fired when organization call action is triggered	`{ detail: { params: any } }`
`ofl-close-panel`	Fired when close panel action is triggered	`{}`

Context Configuration

The context property accepts a PackageContext object with the following structure:

{
  options?: {
    baseUrl?: string;           // Base URL for the Flow API
    organizationId?: string;    // Organization identifier for the flow
    flowId?: string;           // Flow identifier to load and process
    customStyles?: CSSStyleSheet; // Custom styles to be applied
    initialState?: any;        // Initial state for the flow
    tracking?: boolean;        // Enable tracking functionality
    navigation?: string;       // Navigation type ("default", "accordion")
    inContainer?: boolean;     // Whether flow is displayed in a container
  };
  devMode?: boolean;           // Enable development mode
}

OFL-Stages

Description

A component that displays the current stage in a multi-step process. It adapts responsively to show either a progress bar with current stage name (on smaller screens) or a list of all stages (on larger screens).

Importing

// ESM/Bundler Import
import "@onlive.site/flow/components/stages/stages.js";

// Script Import (CDN)
<script
  type="module"
  src="https://cdn.onlive.site/@onlive.site/flow@latest/components/stages/stages.js"
></script>;

Then use the component in your HTML:

<ofl-stages
  active="stage-2"
  .stages=${[
    { id: "stage-1", name: "Personal Info" },
    { id: "stage-2", name: "Address" },
    { id: "stage-3", name: "Review" }
  ]}
></ofl-stages>

Properties

Name	Type	Description	Reflects	Default Value
`context`	`PackageContext`	Package context with custom styles	`false`	`undefined`
`active`	`String`	ID of the currently active stage	`false`	`undefined`
`stages`	`Array<{id: string, name: string}>`	Array of stage definitions	`false`	`[]`
`position`	`"header" \| "footer"`	Display position of the stages	`false`	`"header"`
`navigation`	`"steps" \| "accordion"`	Navigation style for the stages	`false`	`"steps"`

OFL-Form

Description

A form component that renders a list of fields and handles their values and validation state. Supports various field types and layouts.

Importing

// ESM/Bundler Import
import "@onlive.site/flow/components/form/form.js";

// Script Import (CDN)
<script
  type="module"
  src="https://cdn.onlive.site/@onlive.site/flow@latest/components/form/form.js"
></script>;

Then use the component in your HTML:

<ofl-form
  .fields=${[
    { name: "fullName", label: "Full Name", type: "text", required: true },
    { name: "email", label: "Email", type: "email", required: true }
  ]}
></ofl-form>

Properties

Name	Type	Description	Reflects	Default Value
`context`	`PackageContext`	Package context with custom styles	`false`	`undefined`
`fields`	`Array<Field>`	Array of field definitions	`false`	`[]`
`readonly`	`Boolean`	Whether the form is in readonly mode	`false`	`false`
`errors`	`Array<{name: string, error: string}>`	Array of field validation errors	`false`	`[]`

Events

Name	Description	Event Detail
`ofl-change`	Fired when form values or validation changes	`{ detail: { values: Record<string, FieldValue \| FieldValue[]>, valid: boolean } }`
`ofl-submit`	Fired when the form is submitted	`{ detail: { action?: string } }`
`ofl-interaction`	Fired when user interacts with form for first time	`{ detail: {} }`

OFL-Field

Description

A versatile form field component that adapts to different input types. Supports inputs, textareas, checkboxes, radio buttons, selects, maps, calendars, and more. Handles validation, value management, and specialized field controllers.

Importing

// ESM/Bundler Import
import "@onlive.site/flow/components/field/field.js";

// Script Import (CDN)
<script
  type="module"
  src="https://cdn.onlive.site/@onlive.site/flow@latest/components/field/field.js"
></script>;

Then use the component in your HTML:

<ofl-field
  .field=${{
    name: "email",
    label: "Email Address",
    type: "email",
    component: "input",
    required: true
  }}
></ofl-field>

Check the Field Types documentation for a complete list of supported field types.

Properties

Name	Type	Description	Reflects	Default Value
`context`	`PackageContext`	Package context with custom styles	`false`	`undefined`
`field`	`Field`	Field configuration object	`false`	`undefined`
`name`	`String`	Field name identifier	`true`	`undefined`
`errorMessage`	`String`	External error message to display	`true`	`''`
`type`	`String`	Field input type (text, number, etc.)	`true`	`undefined`
`component`	`String`	Component to render (input, select)	`true`	`undefined`

Events

Name	Description	Event Detail
`ofl-change`	Fired when the field value changes	`{ detail: { value: FieldValue \| FieldValue[] \| undefined, valid: boolean } }`
`ofl-interaction`	Fired when user interacts with field	`{ detail: {} }`
`ofl-submit`	Fired when field triggers form submission	`{ detail: { action?: string } }`

OFL-Actions

Description

A component that renders a collection of action buttons based on the provided configuration. Supports various button types, variants, loading states, and handles action click events.

Importing

// ESM/Bundler Import
import "@onlive.site/flow/components/actions/actions.js";

// Script Import (CDN)
<script
  type="module"
  src="https://cdn.onlive.site/@onlive.site/flow@latest/components/actions/actions.js"
></script>;

Then use the component in your HTML:

<ofl-actions
  .actions=${[
    { id: "back", label: "Back", type: "back", variant: "secondary" },
    { id: "next", label: "Continue", type: "submit", variant: "primary" }
  ]}
></ofl-actions>

Properties

Name	Type	Description	Reflects	Default Value
`actions`	`Array<Action>`	Array of action configurations	`false`	`[]`

Events

Name	Description	Event Detail
`ofl-action-click`	Fired when an action button is clicked	`{ detail: { action: Action } }`

Theming

The individual components: ofl-flow, ofl-stages, ofl-form, ofl-field, and ofl-actions can accept a customStyles property that allows you to pass a custom CSS stylesheet to override the default styles of the components.

The main ofl-flow component take the styles configuration from Onlive Flow installation configuration.

Base theming

The Onlive Flow package use the Onlive UI components library for styling and theming. For general theming purpose such as change color palette or font family use Onlive UI theming documentation and for individual UI component theming use specific component documentation.

Example

This example shows how to create new color palette and customize the button styles. Check to the Onlive UI documentation for more details.

Custom Buttons

:root {
  /* Theme Palette */
  --ol-color-primary-50: rgb(255 248 249);
  --ol-color-primary-100: rgb(254 231 236);
  --ol-color-primary-200: rgb(253 212 220);
  --ol-color-primary-300: rgb(252 190 203);
  --ol-color-primary-400: rgb(251 160 179);
  --ol-color-primary-500: rgb(249 117 145);
  --ol-color-primary-600: rgb(247 52 93);
  --ol-color-primary-700: rgb(217 4 49);
  --ol-color-primary-800: rgb(180 4 41);
  --ol-color-primary-900: rgb(131 3 30);
  --ol-color-primary-950: rgb(85 2 19);
}

/* Button styles */
ol-button::part(base) {
  border-radius: var(--ol-border-radius-pill);
  border: 2px solid var(--ol-color-primary-600);
}

/* Button styles for neutral variant */
ol-button[variant="default"]::part(base) {
  color: var(--ol-color-primary-600);
  font-weight: var(--ol-font-weight-bold);
}

Advanced theming

It is possible to use specific selectors in custom styles to modify each of the components in a granular way.

Example

This example shows how to change the number of actions per row in the ofl-actions component.

Actions per row

/* Change the number of actions per row to 3 */
.ofl__actions {
  grid-template-columns: repeat(3, 1fr);
}

.ofl__actions .ofl__actions__button:last-child {
  grid-column: span 1;
}

Installation​

Workflow​

Components​

OFL-Flow​

Description​

Importing​

Properties​

Events​

Context Configuration​

OFL-Stages​

Description​

Importing​

Properties​

OFL-Form​

Description​

Importing​

Properties​

Events​

OFL-Field​

Description​

Importing​

Properties​

Events​

OFL-Actions​

Description​

Importing​

Properties​

Events​

Theming​

Base theming​

Example​

Advanced theming​

Example​

Installation

Workflow

Components

OFL-Flow

Description

Importing

Properties

Events

Context Configuration

OFL-Stages

Description

Importing

Properties

OFL-Form

Description

Importing

Properties

Events

OFL-Field

Description

Importing

Properties

Events

OFL-Actions

Description

Importing

Properties

Events

Theming

Base theming

Example

Advanced theming

Example