Docs

Javascript

Installation

How to set up Flows in your JavaScript application.

The Flows JS SDK is a lightweight library that allows you to integrate Flows into any application that runs JavaScript. Similar to our React SDK, this SDK includes a components package to simplify getting started with Flows in your application.

Check out our template projects for examples of how to implement Flows in your application.

Install the JavaScript SDK

You can install the Flows JavaScript SDK from npm:

npm i @flows/js

Initialize the SDK

Use the init function to initialize the SDK with your organization ID and environment key, which you can find in the Settings > General and Settings > Environments sections of the Flows dashboard.

main.js
import { init } from "@flows/js";
 
init({
  organizationId: "your-organization-id", // Found in Settings > General
  environment: "production", // Default environment
  userId: "your-user-id", // Identify the user
});

For a full list of supported properties, see the init function documentation.

Add a listener for floating blocks

Here’s a high-level example of rendering floating blocks using a pseudo UI library. Since @flows/js is designed to work with any JavaScript UI library/framework the example is in a generic code that illustrates how to use it with concepts that are common in most UI frameworks.

main.js
import { addFloatingBlocksChangeListener } from "@flows/js";
 
// Pseudo UI library reactive state for managing blocks
const blocksState = uiState();
 
const dispose = addFloatingBlocksChangeListener((blocks) => {
  blocksState.set(blocks);
});
 
// Call `dispose` when you want to stop listening to the changes and avoid memory leaks
dispose();
 
// Define your components and tour components
const components = { ... }
const tourComponents = { ... }
 
// Pseudo UI library code that renders the blocks
const render = () => {
  return blocksState.map(block => {
    if(block.type === "component") {
      const Component = components[block.component]
      return <Component {...block.props} />
    }
 
    if(block.type === "tour-component") {
      const TourComponent = tourComponents[block.component]
      return <TourComponent {...block.props} />
    }
  })
}

Add a listener for slot blocks

Rendering slot-specific blocks can be done by creating a reusable FlowsSlot component. This component listens for changes to slot blocks in a specific slot ID and renders the blocks accordingly.

flows-slot.js
import { addSlotBlocksChangeListener } from "@flows/js";
// Import your components that we defined earlier
import { components, tourComponents } from "@/my-flows-components";
 
// Pseudo UI library reactive state
const mySlotBlocksState = uiState();
 
const dispose = addSlotBlocksChangeListener(
  // Pass a `slotId` prop to the component
  props.slotId,
  (blocks) => {
    blocksState.set(blocks);
  },
);
// Call `dispose` when you want to stop listening to the changes and avoid memory leaks
dispose();
 
// Pseudo UI library code that renders slot
const FlowsSlotRender = () => {
  // Without any blocks, render optional placeholder
  if (mySlotBlocksState.length === 0) return props.placeholder ?? null;
 
  return mySlotBlocksState.map((block) => {
    if (block.type === "component") {
      const Component = components[block.component];
      return <Component {...block.props} />;
    }
 
    if (block.type === "tour-component") {
      const TourComponent = tourComponents[block.component];
      return <TourComponent {...block.props} />;
    }
  });
};

Optional: Use built-in components

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

You can install the Flows JavaScript Components SDK from npm:

npm i @flows/js-components

Then setup the slot components and render function for the floating blocks. Rendering of slot blocks will be handled by the flows-slot element.

main.js
import { init, addFloatingBlocksChangeListener } from "@flows/js";
import { render, updateSlotComponents } from "@flows/js-components";
import * as components from "@flows/js-components/components";
import * as tourComponents from "@flows/js-components/tour-components";
 
// Import the styles or copy them to your project and <link> them in your HTML
import "@flows/js-components/index.css";
 
init({ ... })
updateSlotComponents({ components, tourComponents })
const dispose = addFloatingBlocksChangeListener((blocks) => {
  render({ blocks, components,tourComponents });
});
// Call `dispose` when you want to stop listening to the changes to avoid memory leaks
dispose()

You can then use custom <flows-slot> HTML element with optional placeholder content anywhere in your HTML document to render slottable blocks.

page.html
<body>
  <!-- ... -->
  <flows-slot data-slot-id="my-slot">
    <!-- Optionally you can pass one child element with `data-placeholder` attribute -->
    <div data-placeholder>
      <p>Optionally pass placeholder content here</p>
    </div>
  </flows-slot>
  <!-- ... -->
</body>

Create your first workflow

That's it! You're now ready to create your first workflow. See our quickstart guide for more information.

On this page