useFunnel()

useFunnel() is a React Hook (opens in a new tab) that makes it easier to implement complex UI flows. Hooks are functions you use within React components. Hooks allow you to manage the state and lifecycle of components.

Interface

useFunnel() takes the UseFunnelOptions option and returns the UseFunnelResults object.

function useFunnel<T>(options: UseFunnelOptions<T>): UseFunnelResults<T>;

• UseFunnelOptions
• UseFunnelResults
• FunnelHistory
  • RouteOption

UseFunnelOptions

An object that defines the funnel's initial state and the configuration for each step.

interface UseFunnelOptions<T> {
  id: string;
  initial: { step: keyof T, context: T[keyof T] };
  steps?: { [key in keyof T]?: FunnelStepOption<T[key]> };
}

• id (string, required): A unique identifier for the funnel. This identifier is used to identify and manage funnel instances.
• initial (object, required): Defines the initial state of the funnel. step contains the key of T object, and context contains the value of that key.
  • step (string): The name of the initial step.
  • context (object): An object representing the state of the initial step.
• steps (object, optional): Defines the options for each step. Use the key of the T object to receive a FunnelStepOption object as the value.

FunnelStepOption

FunnelStepOption is an interface that defines additional options for each step.

interface FunnelStepOption<TContext> {
  guard?: (data: unknown) => data is TContext;
  parse?: (data: unknown) => TContext;
}

• guard (function, optional): A function that validates the data to determine if it is the context type of that step.
• parse (function, optional): A function that converts the data into the context type for that step.

UseFunnelResults

Contains properties and methods to manage the state and history of the funnel.

type UseFunnelResults<T> = {
  [key in keyof T]: {
    step: key
    context: T[key];
    history: FunnelHistory<T, T[key]>;
  }
}[keyof T] & {
  index: number;
  historySteps: { step: keyof T, context: T[keyof T] }[];
  Render: FunnelRenderComponent<T>;
};

• step (string): A property representing the current step in the funnel. It uses the key of the T object.
• context (object): A property that represents the state of the current step. It contains the value of the T object defined according to the value of the step property.
• history (object): An object managing the transitions of the funnel. Use it to move to the next step or return to the previous step. For more information, see FunnelHistory.
• index (number): The index of the current step of the funnel. It is the same as the index of the historySteps array.
• historySteps (array): An array that represents the funnel's history. Each object contains the step name and context of the step.
• <Render /> (function): A component for rendering. For more information, see <funnel.Render />.

FunnelHistory

An object that manages the transitions of the funnel. It contains several methods for handling the transition of the funnel steps.

interface FunnelHistory<TContextMap, TCurrentStep extends keyof TContextMap> {
  push: <TTargetStep extends keyof TContextMap>(
    step: TTargetStep,
    context: TContextMap[TTargetStep] | ((prev: TContextMap<TCurrentStep>) => T[TTargetStep]),
    routeOption?: RouteOption
  ) => Promise<void> | void;
  replace: <TTargetStep extends keyof TContextMap>(
    step: TTargetStep,
    context: TContextMap[TTargetStep] | ((prev: TContextMap<TCurrentStep>) => T[TTargetStep]),
    routeOption?: RouteOption
  ) => Promise<void> | void;
  go: (index: number) => void | Promise<void>;
  back: () => void | Promise<void>;
}

• push (function): Adds a new state and moves to the next funnel step.
  • step (string): The name of the next step.
  • context (object | function): An object representing the state of the next step. You can also pass a function that uses the current step state to create the next step state.
  • routeOption (object): A routing option that can be set for the next step. Different options are provided for each package. For more information, see RouteOption.
• replace (function): Replaces the current state with a new one and transitions to the next step.
  • step (string): The name of the next step.
  • context (object | function): An object representing the state of the next step. You can also pass a function that uses the current step state to create the next step state.
  • routeOption (object): A routing option that can be set for the next step. Different options are provided for each package. For more information, see RouteOption.
• go (function): Moves to the step at the specified index in the historySteps array.
  • index (number): The index of the step to move to.
• back (function): Moves to the previous step.

RouteOption

interface RouteOption {
  scroll?: boolean;
  locale?: string;
  shallow?: boolean;
}

Example

Basic Usage

import { useFunnel, UseFunnelOptions, UseFunnelResults } from "@use-funnel/next";
 
type T = {
  helloStep: { message: string; };
  worldStep: { message: string; message2: string }
}
 
const funnel: UseFunnelResults<T> = useFunnel<T>({
  id: "use-funnel-api-reference",
  steps: {},
  initial: {
    step: "helloStep",
    context: {
      message: 'Hello'
    }
  },
} satisfies UseFunnelOptions<T>);

History Management Example

import { useFunnel } from "@use-funnel/next";
 
type T = {
  helloStep: { message: string; };
  worldStep: { message: string; message2: string }
}
 
const funnel = useFunnel<T>({
  id: "use-funnel-history-example",
  steps: {},
  initial: {
    step: "helloStep",
    context: {
      message: 'Hello'
    }
  },
});
 
if (funnel.step === 'helloStep') {
  funnel.history.push('worldStep', { message2: 'World' });
}