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
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 ofT
object, andcontext
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 theT
object to receive aFunnelStepOption
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, seeFunnelHistory
.index
(number
): The index of the current step of the funnel. It is the same as the index of thehistorySteps
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 thehistorySteps
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;
}
For more information, see the documentation (opens in a new tab) for the package.
At @use-funnel/next
, the shallow
option is intentionally set to true
by default.
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' });
}