Skip to main content

@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

NameTypeDescriptionReflectsDefault Value
contextPackageContextPackage context containing flow configurationfalseundefined

Events

NameDescriptionEvent Detail
ofl-changeFired when form field values change{ detail: { values: Record<string, FieldValue>, valid: boolean } }
ofl-action-clickFired when an action button is clicked{ detail: { action: Action } }
ofl-organization-callFired when organization call action is triggered{ detail: { params: any } }
ofl-close-panelFired 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

NameTypeDescriptionReflectsDefault Value
contextPackageContextPackage context with custom stylesfalseundefined
activeStringID of the currently active stagefalseundefined
stagesArray<{id: string, name: string}>Array of stage definitionsfalse[]
position"header" | "footer"Display position of the stagesfalse"header"
navigation"steps" | "accordion"Navigation style for the stagesfalse"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

NameTypeDescriptionReflectsDefault Value
contextPackageContextPackage context with custom stylesfalseundefined
fieldsArray<Field>Array of field definitionsfalse[]
readonlyBooleanWhether the form is in readonly modefalsefalse
errorsArray<{name: string, error: string}>Array of field validation errorsfalse[]

Events

NameDescriptionEvent Detail
ofl-changeFired when form values or validation changes{ detail: { values: Record<string, FieldValue | FieldValue[]>, valid: boolean } }
ofl-submitFired when the form is submitted{ detail: { action?: string } }
ofl-interactionFired 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

NameTypeDescriptionReflectsDefault Value
contextPackageContextPackage context with custom stylesfalseundefined
fieldFieldField configuration objectfalseundefined
nameStringField name identifiertrueundefined
errorMessageStringExternal error message to displaytrue''
typeStringField input type (text, number, etc.)trueundefined
componentStringComponent to render (input, select)trueundefined

Events

NameDescriptionEvent Detail
ofl-changeFired when the field value changes{ detail: { value: FieldValue | FieldValue[] | undefined, valid: boolean } }
ofl-interactionFired when user interacts with field{ detail: {} }
ofl-submitFired 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

NameTypeDescriptionReflectsDefault Value
actionsArray<Action>Array of action configurationsfalse[]

Events

NameDescriptionEvent Detail
ofl-action-clickFired 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;
}