@flows/react/dist/index.d.ts

Flows React SDK – Build native product growth experiences, your way

import { ReactNode, FC } from 'react';

/**
 * Properties provided by Flows based on block and block template setup.
 */
interface FlowsProperties {
    /**
     * 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.
     */
    id: string;
    /**
     * User defined key for identifying the block.
     */
    key?: string;
    /**
     * Id of the workflow this block belongs to.
     */
    workflowId: string;
    /**
     * Total number of visible tour steps (components) in the current tour. Logic steps (e.g. wait) are not counted.
     */
    tourVisibleStepCount?: number;
    /**
     * 0-based index of the currently visible tour step (component) in the current tour. Logic steps (e.g. wait) are not counted.
     */
    tourVisibleStepIndex?: number;
}
type ComponentProps<T extends Record<string, any> = any> = {
    /**
     * Properties provided by Flows based on block and block template setup.
     */
    __flows: FlowsProperties;
} & T;
type TourComponentProps<T extends Record<string, any> = any> = {
    /**
     * Properties provided by Flows based on block and block template setup.
     */
    __flows: FlowsProperties;
    continue: () => void;
    previous?: () => void;
    cancel: () => void;
} & T;
type StateMemoryTriggerType = "transition" | "manual";
interface StateMemoryTrigger {
    /**
     * Type of the trigger.
     */
    type: StateMemoryTriggerType;
    /**
     * Id of the block that will set the state memory to true when it is exited.
     */
    blockId?: string;
    /**
     * User defined key for identifying the tracked block.
     */
    blockKey?: string;
}
/**
 * The object representing state memory property in your component properties.
 */
interface StateMemory {
    /**
     * Boolean value of the state memory property.
     */
    value: boolean;
    /**
     * Update the state memory property.
     * @param value - new boolean value to set
     */
    setValue: (value: boolean) => void;
    /**
     * Triggers you have setup in the workflow for this state memory property.
     */
    triggers: StateMemoryTrigger[];
}
/**
 * The object representing action property in your component properties.
 */
interface Action {
    /**
     * The label of the element used to trigger the action (eg. button text).
     */
    label: string;
    /**
     * Optional URL to navigate to when the action is triggered.
     * When provided no special handling is done, you need to handle the navigation yourself using a link or similar.
     */
    url?: string;
    /**
     * Optional flag to open the URL in a new tab.
     * When provided no special handling is done, you need to pass this to the element that will handle the navigation.
     */
    openInNew?: boolean;
    /**
     * Function to call when the action is triggered.
     * Currently supports only transition to a specified exit node.
     */
    callAction?: () => Promise<void>;
}
/**
 * The object representing block state of the selected block in the workflow.
 * The properties of this object are the same as the properties of the block.
 */
type BlockState<T extends Record<string, any> = any> = ComponentProps<T>;

interface ActiveBlock {
    /**
     * 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.
     */
    id: string;
    /**
     * Unique identifier of the tour block this tour-component belongs to. Keep in mind each workflow version will have a different id for each block.
     */
    tourBlockId?: string;
    /**
     * Type of the block, either "component" or "tour-component".
     */
    type: "component" | "tour-component";
    /**
     * The UI Component used to render this block.
     */
    component: string;
    /**
     * Props to be passed to the component including both data and exit node methods.
     */
    props: {
        __flows: FlowsProperties;
    } & Record<string, unknown>;
}

type LanguageOption = "disabled" | "automatic" | Locale;
/**
 * Full list of supported locales coming from the browser `navigator.language`. Source: [https://www.localeplanet.com/icu/](https://www.localeplanet.com/icu/).
 */
type Locale = "af" | "af-NA" | "af-ZA" | "agq" | "agq-CM" | "ak" | "ak-GH" | "am" | "am-ET" | "ar" | "ar-001" | "ar-AE" | "ar-BH" | "ar-DJ" | "ar-DZ" | "ar-EG" | "ar-EH" | "ar-ER" | "ar-IL" | "ar-IQ" | "ar-JO" | "ar-KM" | "ar-KW" | "ar-LB" | "ar-LY" | "ar-MA" | "ar-MR" | "ar-OM" | "ar-PS" | "ar-QA" | "ar-SA" | "ar-SD" | "ar-SO" | "ar-SS" | "ar-SY" | "ar-TD" | "ar-TN" | "ar-YE" | "as" | "as-IN" | "asa" | "asa-TZ" | "ast" | "ast-ES" | "az" | "az-Cyrl" | "az-Cyrl-AZ" | "az-Latn" | "az-Latn-AZ" | "bas" | "bas-CM" | "be" | "be-BY" | "bem" | "bem-ZM" | "bez" | "bez-TZ" | "bg" | "bg-BG" | "bm" | "bm-ML" | "bn" | "bn-BD" | "bn-IN" | "bo" | "bo-CN" | "bo-IN" | "br" | "br-FR" | "brx" | "brx-IN" | "bs" | "bs-Cyrl" | "bs-Cyrl-BA" | "bs-Latn" | "bs-Latn-BA" | "ca" | "ca-AD" | "ca-ES" | "ca-FR" | "ca-IT" | "ccp" | "ccp-BD" | "ccp-IN" | "ce" | "ce-RU" | "cgg" | "cgg-UG" | "chr" | "chr-US" | "ckb" | "ckb-IQ" | "ckb-IR" | "cs" | "cs-CZ" | "cy" | "cy-GB" | "da" | "da-DK" | "da-GL" | "dav" | "dav-KE" | "de" | "de-AT" | "de-BE" | "de-CH" | "de-DE" | "de-IT" | "de-LI" | "de-LU" | "dje" | "dje-NE" | "dsb" | "dsb-DE" | "dua" | "dua-CM" | "dyo" | "dyo-SN" | "dz" | "dz-BT" | "ebu" | "ebu-KE" | "ee" | "ee-GH" | "ee-TG" | "el" | "el-CY" | "el-GR" | "en" | "en-001" | "en-150" | "en-AG" | "en-AI" | "en-AS" | "en-AT" | "en-AU" | "en-BB" | "en-BE" | "en-BI" | "en-BM" | "en-BS" | "en-BW" | "en-BZ" | "en-CA" | "en-CC" | "en-CH" | "en-CK" | "en-CM" | "en-CX" | "en-CY" | "en-DE" | "en-DG" | "en-DK" | "en-DM" | "en-ER" | "en-FI" | "en-FJ" | "en-FK" | "en-FM" | "en-GB" | "en-GD" | "en-GG" | "en-GH" | "en-GI" | "en-GM" | "en-GU" | "en-GY" | "en-HK" | "en-IE" | "en-IL" | "en-IM" | "en-IN" | "en-IO" | "en-JE" | "en-JM" | "en-KE" | "en-KI" | "en-KN" | "en-KY" | "en-LC" | "en-LR" | "en-LS" | "en-MG" | "en-MH" | "en-MO" | "en-MP" | "en-MS" | "en-MT" | "en-MU" | "en-MW" | "en-MY" | "en-NA" | "en-NF" | "en-NG" | "en-NL" | "en-NR" | "en-NU" | "en-NZ" | "en-PG" | "en-PH" | "en-PK" | "en-PN" | "en-PR" | "en-PW" | "en-RW" | "en-SB" | "en-SC" | "en-SD" | "en-SE" | "en-SG" | "en-SH" | "en-SI" | "en-SL" | "en-SS" | "en-SX" | "en-SZ" | "en-TC" | "en-TK" | "en-TO" | "en-TT" | "en-TV" | "en-TZ" | "en-UG" | "en-UM" | "en-US" | "en-US-POSIX" | "en-VC" | "en-VG" | "en-VI" | "en-VU" | "en-WS" | "en-ZA" | "en-ZM" | "en-ZW" | "eo" | "es" | "es-419" | "es-AR" | "es-BO" | "es-BR" | "es-BZ" | "es-CL" | "es-CO" | "es-CR" | "es-CU" | "es-DO" | "es-EA" | "es-EC" | "es-ES" | "es-GQ" | "es-GT" | "es-HN" | "es-IC" | "es-MX" | "es-NI" | "es-PA" | "es-PE" | "es-PH" | "es-PR" | "es-PY" | "es-SV" | "es-US" | "es-UY" | "es-VE" | "et" | "et-EE" | "eu" | "eu-ES" | "ewo" | "ewo-CM" | "fa" | "fa-AF" | "fa-IR" | "ff" | "ff-CM" | "ff-GN" | "ff-MR" | "ff-SN" | "fi" | "fi-FI" | "fil" | "fil-PH" | "fo" | "fo-DK" | "fo-FO" | "fr" | "fr-BE" | "fr-BF" | "fr-BI" | "fr-BJ" | "fr-BL" | "fr-CA" | "fr-CD" | "fr-CF" | "fr-CG" | "fr-CH" | "fr-CI" | "fr-CM" | "fr-DJ" | "fr-DZ" | "fr-FR" | "fr-GA" | "fr-GF" | "fr-GN" | "fr-GP" | "fr-GQ" | "fr-HT" | "fr-KM" | "fr-LU" | "fr-MA" | "fr-MC" | "fr-MF" | "fr-MG" | "fr-ML" | "fr-MQ" | "fr-MR" | "fr-MU" | "fr-NC" | "fr-NE" | "fr-PF" | "fr-PM" | "fr-RE" | "fr-RW" | "fr-SC" | "fr-SN" | "fr-SY" | "fr-TD" | "fr-TG" | "fr-TN" | "fr-VU" | "fr-WF" | "fr-YT" | "fur" | "fur-IT" | "fy" | "fy-NL" | "ga" | "ga-IE" | "gd" | "gd-GB" | "gl" | "gl-ES" | "gsw" | "gsw-CH" | "gsw-FR" | "gsw-LI" | "gu" | "gu-IN" | "guz" | "guz-KE" | "gv" | "gv-IM" | "ha" | "ha-GH" | "ha-NE" | "ha-NG" | "haw" | "haw-US" | "he" | "he-IL" | "hi" | "hi-IN" | "hr" | "hr-BA" | "hr-HR" | "hsb" | "hsb-DE" | "hu" | "hu-HU" | "hy" | "hy-AM" | "id" | "id-ID" | "ig" | "ig-NG" | "ii" | "ii-CN" | "is" | "is-IS" | "it" | "it-CH" | "it-IT" | "it-SM" | "it-VA" | "ja" | "ja-JP" | "jgo" | "jgo-CM" | "jmc" | "jmc-TZ" | "ka" | "ka-GE" | "kab" | "kab-DZ" | "kam" | "kam-KE" | "kde" | "kde-TZ" | "kea" | "kea-CV" | "khq" | "khq-ML" | "ki" | "ki-KE" | "kk" | "kk-KZ" | "kkj" | "kkj-CM" | "kl" | "kl-GL" | "kln" | "kln-KE" | "km" | "km-KH" | "kn" | "kn-IN" | "ko" | "ko-KP" | "ko-KR" | "kok" | "kok-IN" | "ks" | "ks-IN" | "ksb" | "ksb-TZ" | "ksf" | "ksf-CM" | "ksh" | "ksh-DE" | "kw" | "kw-GB" | "ky" | "ky-KG" | "lag" | "lag-TZ" | "lb" | "lb-LU" | "lg" | "lg-UG" | "lkt" | "lkt-US" | "ln" | "ln-AO" | "ln-CD" | "ln-CF" | "ln-CG" | "lo" | "lo-LA" | "lrc" | "lrc-IQ" | "lrc-IR" | "lt" | "lt-LT" | "lu" | "lu-CD" | "luo" | "luo-KE" | "luy" | "luy-KE" | "lv" | "lv-LV" | "mas" | "mas-KE" | "mas-TZ" | "mer" | "mer-KE" | "mfe" | "mfe-MU" | "mg" | "mg-MG" | "mgh" | "mgh-MZ" | "mgo" | "mgo-CM" | "mk" | "mk-MK" | "ml" | "ml-IN" | "mn" | "mn-MN" | "mr" | "mr-IN" | "ms" | "ms-BN" | "ms-MY" | "ms-SG" | "mt" | "mt-MT" | "mua" | "mua-CM" | "my" | "my-MM" | "mzn" | "mzn-IR" | "naq" | "naq-NA" | "nb" | "nb-NO" | "nb-SJ" | "nd" | "nd-ZW" | "nds" | "nds-DE" | "nds-NL" | "ne" | "ne-IN" | "ne-NP" | "nl" | "nl-AW" | "nl-BE" | "nl-BQ" | "nl-CW" | "nl-NL" | "nl-SR" | "nl-SX" | "nmg" | "nmg-CM" | "nn" | "nn-NO" | "nnh" | "nnh-CM" | "nus" | "nus-SS" | "nyn" | "nyn-UG" | "om" | "om-ET" | "om-KE" | "or" | "or-IN" | "os" | "os-GE" | "os-RU" | "pa" | "pa-Arab" | "pa-Arab-PK" | "pa-Guru" | "pa-Guru-IN" | "pl" | "pl-PL" | "ps" | "ps-AF" | "pt" | "pt-AO" | "pt-BR" | "pt-CH" | "pt-CV" | "pt-GQ" | "pt-GW" | "pt-LU" | "pt-MO" | "pt-MZ" | "pt-PT" | "pt-ST" | "pt-TL" | "qu" | "qu-BO" | "qu-EC" | "qu-PE" | "rm" | "rm-CH" | "rn" | "rn-BI" | "ro" | "ro-MD" | "ro-RO" | "rof" | "rof-TZ" | "ru" | "ru-BY" | "ru-KG" | "ru-KZ" | "ru-MD" | "ru-RU" | "ru-UA" | "rw" | "rw-RW" | "rwk" | "rwk-TZ" | "sah" | "sah-RU" | "saq" | "saq-KE" | "sbp" | "sbp-TZ" | "se" | "se-FI" | "se-NO" | "se-SE" | "seh" | "seh-MZ" | "ses" | "ses-ML" | "sg" | "sg-CF" | "shi" | "shi-Latn" | "shi-Latn-MA" | "shi-Tfng" | "shi-Tfng-MA" | "si" | "si-LK" | "sk" | "sk-SK" | "sl" | "sl-SI" | "smn" | "smn-FI" | "sn" | "sn-ZW" | "so" | "so-DJ" | "so-ET" | "so-KE" | "so-SO" | "sq" | "sq-AL" | "sq-MK" | "sq-XK" | "sr" | "sr-Cyrl" | "sr-Cyrl-BA" | "sr-Cyrl-ME" | "sr-Cyrl-RS" | "sr-Cyrl-XK" | "sr-Latn" | "sr-Latn-BA" | "sr-Latn-ME" | "sr-Latn-RS" | "sr-Latn-XK" | "sv" | "sv-AX" | "sv-FI" | "sv-SE" | "sw" | "sw-CD" | "sw-KE" | "sw-TZ" | "sw-UG" | "ta" | "ta-IN" | "ta-LK" | "ta-MY" | "ta-SG" | "te" | "te-IN" | "teo" | "teo-KE" | "teo-UG" | "tg" | "tg-TJ" | "th" | "th-TH" | "ti" | "ti-ER" | "ti-ET" | "to" | "to-TO" | "tr" | "tr-CY" | "tr-TR" | "tt" | "tt-RU" | "twq" | "twq-NE" | "tzm" | "tzm-MA" | "ug" | "ug-CN" | "uk" | "uk-UA" | "ur" | "ur-IN" | "ur-PK" | "uz" | "uz-Arab" | "uz-Arab-AF" | "uz-Cyrl" | "uz-Cyrl-UZ" | "uz-Latn" | "uz-Latn-UZ" | "vai" | "vai-Latn" | "vai-Latn-LR" | "vai-Vaii" | "vai-Vaii-LR" | "vi" | "vi-VN" | "vun" | "vun-TZ" | "wae" | "wae-CH" | "wo" | "wo-SN" | "xog" | "xog-UG" | "yav" | "yav-CM" | "yi" | "yi-001" | "yo" | "yo-BJ" | "yo-NG" | "yue" | "yue-Hans" | "yue-Hans-CN" | "yue-Hant" | "yue-Hant-HK" | "zgh" | "zgh-MA" | "zh" | "zh-Hans" | "zh-Hans-CN" | "zh-Hans-HK" | "zh-Hans-MO" | "zh-Hans-SG" | "zh-Hant" | "zh-Hant-HK" | "zh-Hant-MO" | "zh-Hant-TW" | "zu" | "zu-ZA";

interface LinkComponentProps {
    children?: ReactNode;
    href: string;
    className?: string;
    onClick?: () => void;
}
type LinkComponentType = FC<LinkComponentProps>;

type UserProperties = Record<string, string | number | boolean | null | Date | undefined>;

interface FlowsSlotProps {
    id: string;
    placeholder?: ReactNode;
}
declare const FlowsSlot: FC<FlowsSlotProps>;

type Component = FC<ComponentProps>;
type Components = Record<string, Component>;
type TourComponent = FC<TourComponentProps>;
type TourComponents = Record<string, TourComponent>;

interface FlowsProviderProps {
    /**
     * Your organization ID. Find this in Settings \> General.
     */
    organizationId: string;
    /**
     * The environment key. Find this in Settings \> Environments.
     */
    environment: string;
    /**
     * Unique ID used to identify the user.
     *
     * If set to `null`, the SDK will be disabled and `children` will render while waiting for the `userId`. This is useful when loading the ID asynchronously.
     */
    userId: string | null;
    /**
     * Object with custom [user properties](https://flows.sh/docs/users/properties). Values can be string, number, boolean, or date.
     */
    userProperties?: UserProperties;
    /**
     * Custom API URL useful when using proxy to send Flows requests through your own domain.
     */
    apiUrl?: string;
    /**
     * Components used for workflow blocks.
     */
    components: Components;
    /**
     * Components used for tour blocks.
     */
    tourComponents: TourComponents;
    /**
     * Language used to enable [localization](https://flows.sh/docs/localization). Based on the set language, the correct translation for the block data will be selected.
     * - `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/](https://www.localeplanet.com/icu/) for a full list of supported languages.
     * @default "disabled"
     */
    language?: LanguageOption;
    /**
     * Enables the debug panel. Can be also invoked by pressing `Cmd + Option + Shift + F` on Mac or `Ctrl + Alt + Shift + F` on Windows/Linux.
     *
     * Disabled by default. Defaults to `true` when running on `localhost`.
     *
     * Passing `false` here will NOT disable the shortcut.
     */
    debug?: boolean;
    /**
     * 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.
     *
     * Use this function to customize the shortcut or disable it entirely.
     *
     * @param event - The `keydown` keyboard event to evaluate
     * @returns `true` to open the debug panel, `false` to ignore the shortcut
     *
     * @example
     * ```ts
     * // Disable debug panel shortcut
     * onDebugShortcut={() => false}
     *
     * // Use custom shortcut
     * onDebugShortcut={(e) => {
     *   return e.ctrlKey && e.key === "c"
     * }}
     * ```
     */
    onDebugShortcut?: (event: KeyboardEvent) => boolean;
    /**
     * Custom Link component used for client-side navigation when using components from `@flows/react-components`. Otherwise each link click will result in a full page reload.
     *
     * Expects link component from your router, for example Link from "next/link". The LinkComponent should accept `href`, `className`, `onClick` and `children` props and render html `<a>` element.
     *
     * The LinkComponent will be used for all URLs without domain and without "openInNew" (target="_blank").
     * - `/about` - internal link, use LinkComponent
     * - `?search=test` - internal link, use LinkComponent
     * - `https://example.com` - external link, use standard `<a>` element
     * - `/about` with `openInNew` - external link, use standard `<a>` element with `target="_blank"`
     *
     * @example
     * ```tsx
     * import { Link } from "react-router";
     * import { LinkComponentType } from "@flows/react";
     *
     * // Adapt "react-router" Link to Flows LinkComponentType
     * const LinkComponent: LinkComponentType = ({ href, children, className, onClick }) => (
     *   <Link to={href} className={className} onClick={onClick}>
     *     {children}
     *   </Link>
     * )
     *
     * // Pass the LinkComponent to FlowsProvider
     * <FlowsProvider
     *   LinkComponent={LinkComponent}
     * />
     * ```
     */
    LinkComponent?: LinkComponentType;
    children: ReactNode;
}
declare const FlowsProvider: FC<FlowsProviderProps>;

/**
 * Get all the currently displayed workflow and tour blocks that are not slottable.
 * @returns array of `ActiveBlock` objects
 */
declare const useCurrentFloatingBlocks: () => ActiveBlock[];
/**
 * Get all the currently displayed workflow and tour blocks for a specific slot.
 * @param slotId - the slot id to get the blocks for
 * @returns array of `ActiveBlock` objects
 */
declare const useCurrentSlotBlocks: (slotId: string) => ActiveBlock[];

/**
 * Reset progress for all workflows for the current user in the current environment.
 */
declare const resetAllWorkflowsProgress: () => Promise<void>;
/**
 * Reset progress of one workflow for the current user in the current environment.
 * @param workflowId - UUID of the workflow to reset progress for
 */
declare const resetWorkflowProgress: (workflowId: string) => Promise<void>;
/**
 * Start a workflow from a manual start block. The workflow will only start 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
 * @param blockKey - block key of the manual start block
 */
declare const startWorkflow: (blockKey: string) => Promise<void>;

export { type Action, type ActiveBlock, type BlockState, type ComponentProps, type FlowsProperties, FlowsProvider, FlowsSlot, type FlowsSlotProps, type LanguageOption, type LinkComponentProps, type LinkComponentType, type Locale, type StateMemory, type TourComponentProps, resetAllWorkflowsProgress, resetWorkflowProgress, startWorkflow, useCurrentFloatingBlocks, useCurrentSlotBlocks };