Userflow.js API Reference

The userflow global object

Once you've installed Userflow.js in your web app, a userflow object will be available globally on window in users' browsers.


Initializes Userflow.js to target your company. Must be called once (per page load) before you make any other call.

Parameter Type Description
token String, required Your Userflow Token, which you can find under Settings.



userflow.identify(userId, properties)

Informs Userflow of a user that's signed into your app. You should call this once on any page load where a user is authenticated.

If properties is set, the given properties will be merged into the user's existing data in Userflow. Any properties you leave out will be left as-is in Userflow.

It's up to you which properties you want to send to Userflow. The only required field is userId. Make sure not to send any sensitive data such as passwords. We recommend sending name and/or email so you can easily tell users apart in Userflow without relying on IDs only.

If the user has any active flows, they will be displayed.

Parameter Type Description
userId String, required The user's ID in your database.
properties Object, optional An object with attributes you know about the user. String, optional User's name String, optional User's email
properties.signedUpAt String, optional Date and time (in ISO 8601 format) the user signed up for your service.
properties.traits Object, optional An object with any other custom traits that you want to store with the user. These traits can be used in flow content and conditions to personalize the user experience. Each trait is a key-value pair. The key must be snake_cased (i.e. all lower case with _ as word separator). Values can be either strings, integers, decimals, booleans or datetimes (in ISO 8601 format).

Returns a Promise that resolves once the identify call succeeds.

Minimal example of only sending userId:


Example of sending all standard properties and a few custom traits:

userflow.identify('123456', {
  name: 'Jane Smith',
  email: '',
  createdAt: '2019-06-14T16:25:49Z',
  traits: {
    user_role: 'admin',
    items_created_total: 42


Returns true if userflow.identify has been called. false otherwise.


Updates properties for a user that has already been identified with userflow.identify since the last page load.

Use this if you need to update a property after some event happens.

The properties argument takes the exact same format as in userflow.identify.

Example of updating a user's favorite color after they pick it in your UI:

  traits: {
    favorite_color: 'red'

Returns a Promise that resolves once the update succeeds.


Starts a flow for the currently signed-in user. The flow will display immediately.

Use this to programmatically start a flow when something happens in your app. You could, for example, implement a button called "Show onboarding tutorial again", which users can click after signing up to go through your tutorial again.

Parameter Type Description
flowId String, required ID of the flow to start. You can find a flow's ID in Userflow on the flow's "Link/Embed" tab. It's also the ID you see in the URL: /app/{company}/flows/{flowId}

Returns a Promise that resolves once the flow has been started.




Ends all currently active flows, if any, for the user. The flows will be hidden immediately.

If the user does not have any active flows, nothing happens.


Makes Userflow forget about the currently active user and immediately hides any active flows.

Call this when users sign out of your app.

userflow.on(eventName, listener)

Registers an event listener to be called when the given event is triggered.

Parameter Type Description
eventName String, required Name of event to listen for. See list of supported events below.
listener Function, required Function to call when the event is triggered. Depending on the event, the function may receive arguments.

Supported events:

Event Arguments Description
flowvisibilitychange visible (boolean) Called with visible = true when a flow is shown (started) or with visible = fale when a flow is hidden (ended).


const listener = visible => {
  console.log(visible ? 'Flow is visible' : 'Flow was hidden')
userflow.on('flowvisibilitychange', listener)

// ...later, when no longer needed:'flowvisibilitychange', listener), listener)

Removes an event listener previously registered with userflow.on.

Parameter Type Description
flowId String, required Name of event.
listener Function, required Function to that was added with userflow.on.


Teaches Userflow.js to treat specific elements as custom text inputs.

This is useful if, for example, you use combo boxes and want Userflow to treat them like regular <input> elements. Instead of reading a value property (as we do with input elements), the text content of the custom input element is used instead.

Parameter Type Description
customInputSelector String or null, required Valid CSS selector or null to turn off. Note that you can include multiple types of custom inputs by separating each selector with a comma.

Example HTML markup:

<div class="combo-box">
  <div class="combo-box-value">Banana</div>
  <div class="combo-box-trigger">..icon..</div>

Example Userflow.js configuration:


It's now possible to make conditions in the Flow Builder using the value of inputs labeled with Fruit. It works just as if the markup had been like this:

<div class="combo-box">
  <input type="text" value="Banana" />
  <div class="combo-box-trigger">..icon..</div>


By default, when performing Go to page actions, Userflow will cause full page loads using window.location.href = url.

Call this function to override this behavior.

This is useful for single page applications using in-app navigation through the window.history API.

Parameter Type Description
customNavigate Function or null, required A function taking a single string url parameter. Or null to turn off and use default behavior.

Example, where myRouter is a fictive router object:

userflow.setCustomNavigate(url => myRouter.push(url))

Example with React Router app:

// File: history.js
import {createBrowserHistory} from 'history'

export default createBrowserHistory()

// File: index.js
import {Router} from 'react-router-dom'
import history from './history'
import App from './App'

  <Router history={history}>
    <App />
), document.body)

// File: wherever-you-load-userflow.js
import history from './history'

// ...
userflow.setCustomNavigate(url => history.push(url))
// ...


By default, when Userflow needs to scroll an element (e.g. the target of a tooltip) into view, we use the built-in Element.prototype.scrollIntoView method. This doesn't work well with sticky header/footers, since the element may be scrolled within the browser's viewport, but still be below the sticky header/footer.

To get around this, you can instruct Userflow to scroll just a little further in any direction in order to get the element inside the viewport and away from the sticky header/footer.

Note that this behavior will not work, and we'll fall back to plain Element.prototype.scrollIntoView, if the target element is nested within other scroll containers.

Parameter Type Description
scrollPadding Object or null Set to an object to use scroll padding. Set to null to turn off again. Number, optional Padding from the top of the viewport (pixels)
scrollPadding.right Number, optional Padding from the right of the viewport (pixels)
scrollPadding.bottom Number, optional Padding from the bottom of the viewport (pixels)
scrollPadding.left Number, optional Padding from the left of the viewport (pixels)

Example, if you have a 50px tall sticky header:

userflow.setScrollPadding({top: 50})

Example, if you have a 50px tall sticky header and a 20px tall sticky footer:

userflow.setScrollPadding({top: 50, bottom: 20})

To turn off again:


Got questions? We're here for you!

The best way to get help is to
We usually reply within 5 minutes
You can also send an email to
We usually reply within a few hours