Reference

@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.

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:

addFloatingBlocksChangeListener()

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

Parameters:

Returns:

A function to unsubscribe the listener and avoid memory leaks.

addSlotBlocksChangeListener()

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

Parameters:

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:

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:

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:

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.

ComponentProps

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

StateMemory

Represents the state memory property of a block.

triggers type:

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.

@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

render()

Renders floating blocks into the body element. This should be called every time the floating blocks change.

Parameters:

import { addFloatingBlocksChangeListener } from "@flows/js";
import { render } from "@flows/js-components";
 
addFloatingBlocksChangeListener((blocks) => {
  render({
    blocks,
    components: {},
    tourComponents: {},
  });
});

updateSlotComponents()

Updates the components available for slot-based rendering and registers <flows-slot> element.

Parameters:

import { updateSlotComponents } from "@flows/js-components";
 
updateSlotComponents({
  components: {},
  tourComponents: {},
});

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 updateSlotComponents() with your slottable components after initializing the SDK.

<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>

@flows/js-components types

Component

Helps with defining a custom component for use with @flows/js-components. Define the props that you have entered in your block template and return object with root element and cleanup function that will be run before the element is removed from the DOM.

import { Component } from "@flows/js-components";
 
type ModalProps = {
  text: string;
  continue: () => void;
};
 
export const Modal: Component<ModalProps> = (props) => {
  const modal = document.createElement("div");
  modal.className = "my-modal";
 
  const text = document.createElement("p");
  modal.appendChild(text);
  text.textContent = props.text;
 
  const continueButton = document.createElement("button");
  modal.appendChild(continueButton);
  continueButton.textContent = "Continue";
  continueButton.addEventListener("click", props.continue);
 
  return {
    element: modal,
    cleanup: () => {
      continueButton.removeEventListener("click", props.continue);
    },
  };
};