Reference

Discover methods and types available in the @flows/js and @flows/js-components packages.

@flows/js

Flows JS SDK is a lightweight library that allows you to integrate Flows into any application that runs JavaScript.

Install the package from npm:

npm i @flows/js

Methods

init()

Initializes the @flows/js SDK and identifies the user. This method must be called at least once in your application.

main.js

import { init } from "@flows/js";

init({
  organizationId: "your-organization-id", // Find this in Settings > General
  environment: "production", // Default environment
  userId: "your-user-id", // Identify the user
});

Parameters:

Name	Type	Required	Notes
`organizationId`	`string`	Yes	Your organization ID, available in Settings > General.
`environment`	`string`	Yes	The environment key, available in Settings > Environments.
`userId`	`string`	Yes	Unique ID for identifying the user.
`userProperties`	`object`	No	Object with custom user properties as key-value pairs. Accepts `string`, `number`, `boolean`, or `date`.
`language`	LanguageOption	No	The user's language used for localization. When empty the user will receive the default language group.
`apiUrl`	`string`	No	Custom API URL for proxying requests through your domain.
`debug`	`boolean`	No	Enable debug mode to inspect the SDK's behavior.
`onDebugShortcut`	`function`	No	Custom keyboard shortcut handler for opening the debug panel. By default, the debug panel opens with `Cmd + Option + Shift + F` on Mac or `Ctrl + Alt + Shift + F` on Windows/Linux. If you set this prop, the default shortcut will not work.

addFloatingBlocksChangeListener()

Registers a listener for updates to floating workflow and tour blocks. Slottable blocks are not included.

Parameters:

Name	Type	Required	Notes
`listener`	`function`	Yes	Callback invoked with the updated ActiveBlock array.

Returns:

A function to unsubscribe the listener and avoid memory leaks.

addSlotBlocksChangeListener()

Registers a listener for updates to blocks in a specific slot.

Parameters:

Name	Type	Required	Notes
`slotId`	`string`	Yes	Slot ID of the slot to monitor.
`listener`	`function`	Yes	Callback function that receives updated array of ActiveBlock .

Returns:

A function to unsubscribe the listener and avoid memory leaks.

getCurrentFloatingBlocks()

Retrieves all currently active floating workflow and tour blocks. Slot blocks are not included.

Parameters: None

Returns:

An array of ActiveBlock objects.

getCurrentSlotBlocks()

Retrieves all currently active blocks for a specific slot.

Parameters:

Name	Type	Required	Notes
`slotId`	`string`	Yes	Slot ID to query.

Returns:

An array of ActiveBlock objects.

startWorkflow()

Starts a workflow for the current user in the current environment using a the block key of a manual start block. The workflow will start only if:

Workflow is published in the current environment
Workflow has a manual start block with a matching block key
The current user can access the workflow based on the frequency setting
The current user matches the start block's user property conditions

import { startWorkflow } from "@flows/js";

startWorkflow("your-manual-start-block-key");

Parameters:

Name	Type	Required	Notes
`blockKey`	`string`	Yes	The block key of the manual start block you want to trigger. Learn more

Returns: Promise<void>

resetWorkflowProgress()

The resetWorkflowProgress() function resets the progress of a specific workflow for the current user in the current environment.

import { resetWorkflowProgress } from "@flows/js";

document.querySelector("#my-button").addEventListener("click", () => {
  resetWorkflowProgress("workflow-id");
});

Parameters:

Name	Type	Required	Notes
`workflowId`	`string`	Yes	The ID of the workflow to reset. You can find it in the Flows app in the workflow detail.

resetAllWorkflowsProgress()

The resetAllWorkflowsProgress() function resets the progress of all workflows for the current user in the current environment.

import { resetAllWorkflowsProgress } from "@flows/js";

document.querySelector("#my-button").addEventListener("click", () => {
  resetAllWorkflowsProgress();
});

Parameters: None

Types

ActiveBlock

Represents a block visible to the user.

Name	Type	Notes
`id`	`string`	Internal identifier for the block. Changes with every workflow version, for persistent identifier use `props.__flows.key`.
`type`	`"component" \| "tour-component"`	The block type.
`component`	`string`	The UI component that should be used to render the block.
`props`	ComponentProps \| TourComponentProps	Props passed to the component, including data and exit node callbacks.

ComponentProps

Represents the props passed to a component. In addition to your custom props, it includes the __flows object with Flows properties.

Name	Type	Required	Notes
`__flows.id`	`string`	Yes	Unique identifier of the block, useful for stable key during rendering. Keep in mind each workflow version will have a different id for each block.
`__flows.key`	`string`	No	Unique key for the block. Set by you in a workflow. Learn more
`__flows.workflowId`	`string`	Yes	The ID of the workflow. Set by Flows.

StateMemory

Represents the state memory property of a block.

Name	Type	Required	Notes
`value`	`boolean`	Yes	The value of the state memory.
`setValue`	`function`	Yes	Callback to set the value of the state memory.
`triggers`	`array`	Yes	Object with triggers to update the state memory. See table below.

triggers type:

Name	Type	Required	Notes
`type`	`string`	Yes	The trigger type. Can be `manual` or `transition`.
`blockId`	`string`	Yes	The block ID of the block that triggers the state memory.
`blockKey`	`string`	No	The block key of the block that triggers the state memory.

TourComponentProps

Represents the props passed to a tour component. In addition to your custom props, it includes tour component exit nodes and the __flows object with Flows properties.

Name	Type	Required	Notes
`continue`	`function`	Yes	Callback to go to the next step.
`previous`	`function`	No	Callback to go back to the previous step.
`cancel`	`function`	Yes	Callback to cancel the tour.
`__flows.key`	`string`	No	Unique key for the block. Set by you in a workflow. Learn more

BlockState

Represents the block state of the selected block in the workflow.

Name	Type	Required	Notes
Custom block properties	Depends on the property type	Yes	The properties of the selected block in the workflow. The properties are defined on in the block.
`__flows.id`	`string`	Yes	Unique identifier of the block, useful for stable key during rendering. Keep in mind each workflow version will have a different id for each block.
`__flows.key`	`string`	No	Unique key for the block. Set by you in a workflow. Learn more
`__flows.workflowId`	`string`	Yes	The ID of the workflow. Set by Flows.

LanguageOption

Language type used for setting the user's language in the init() function to enable localization.

Options:

disabled (default) - The user will be served content in the default language group of your organization.
automatic - Automatically detect the user's language and use the matching language group. The language is determined by the Navigator.language property in the browser.
Manual - A specific language string, e.g. en-US, fr-FR, etc. This will use the matching language group for the specified language. See https://www.localeplanet.com/icu/ for a full list of supported languages.

@flows/js-components

To simplify implementation, you can use the @flows/js-components package, which provides pre-built UI components and utilities for block rendering.

Install the package from npm:

npm i @flows/js-components

@flows/js-components methods

setupJsComponents()

Defines custom elements for flows-floating-blocks, flows-slot and all the passed UI components.

Parameters:

Name	Type	Required	Notes
`components`	`object`	Yes	Components to use in your workflows.
`tourComponents`	`object`	Yes	Components to use in tour blocks.

import { setupJsComponents } from "@flows/js-components";

import * as components from "@flows/js-components/components";
import * as tourComponents from "@flows/js-components/tour-components";

setupJsComponents({
  components: { ...components },
  tourComponents: { ...tourComponents },
});

flows-floating-blocks

A custom HTML element for rendering floating workflow and tour blocks. For this custom element to function correctly, you need to call setupJsComponents().

index.html

<body>
  <!-- Your app content -->
  <flows-floating-blocks></flows-floating-blocks>
</body>

flows-slot

A custom HTML element for rendering slot blocks. Use the data-slot-id attribute to specify the slot. For this custom element to function correctly, you need to call setupJsComponents().

page.html

<body>
  <!-- ... -->
  <flows-slot data-slot-id="my-slot">
    <!-- Only one child element with `data-placeholder` attribute is supported -->
    <div data-placeholder>
      <p>Optionally pass placeholder content here</p>
    </div>
  </flows-slot>
  <!-- ... -->
</body>

On this page