@gfazioli/mantine-onboarding-tour
Version:
A Mantine 9 onboarding tour component with focus-reveal overlays, cutout highlights, step-by-step popover navigation, and compound components for guided user experiences.
87 lines (86 loc) • 4.23 kB
TypeScript
import { OnboardingTourFocusRevealProps } from '../../OnboardingTourFocusReveal/OnboardingTourFocusReveal';
export type OnboardingTourStep<T extends Record<string, unknown> = Record<string, unknown>> = {
/** Unique id of the tour. Will be use for the data-onboarding-tour-id attribute */
id: string;
/** Header of the tour. You can also pass a React component here */
header?: React.ReactNode | ((tourController: OnboardingTourController<T>) => React.ReactNode);
/** Title of the tour. You can also pass a React component here */
title?: React.ReactNode | ((tourController: OnboardingTourController<T>) => React.ReactNode);
/** Custom Content of the tour. You can also pass a React component here */
content?: React.ReactNode | ((tourController: OnboardingTourController<T>) => React.ReactNode);
/** Footer of the tour. You can also pass a React component here */
footer?: React.ReactNode | ((tourController: OnboardingTourController<T>) => React.ReactNode);
/** Props passed to FocusReveal */
focusRevealProps?: OnboardingTourFocusRevealProps | ((tourController: OnboardingTourController<T>) => OnboardingTourFocusRevealProps);
/** Padding around the cutout highlight area for this step. Overrides tour-level `cutoutPadding`. */
cutoutPadding?: number;
/** Border radius of the cutout highlight area for this step. Overrides tour-level `cutoutRadius`. */
cutoutRadius?: number;
} & T;
/** Options for useOnboardingTour() hook */
export type OnboardingTourOptions<T extends Record<string, unknown> = Record<string, unknown>> = {
/** Loop the tour */
loop?: boolean;
/** Triggered when the tour starts */
onOnboardingTourStart?: () => void;
/** Triggered when the tour ends (always called, whether completed or skipped) */
onOnboardingTourEnd?: () => void;
/** Triggered when the tour is completed (user finishes the last step) */
onOnboardingTourComplete?: () => void;
/** Triggered when the tour is skipped (user clicks Skip) */
onOnboardingTourSkip?: () => void;
/** Triggered when the active step changes */
onOnboardingTourChange?: (tourStep: OnboardingTourStep<T>) => void;
};
export type OnboardingTourController<T extends Record<string, unknown> = Record<string, unknown>> = Readonly<{
/** List of tour steps */
tour: OnboardingTourStep<T>[];
/** Current step */
currentStep: OnboardingTourStep<T> | undefined;
/** Current step index of the tour. Zero-based index */
currentStepIndex: number | undefined;
/** ID of the selected tour */
selectedStepId: string | undefined;
/** Set the current index */
setCurrentStepIndex: (index: number) => void;
/** Start the tour */
startTour: () => void;
/** End the tour programmatically */
endTour: () => void;
/** Skip the tour (user dismissed) */
skipTour: () => void;
/** Go to the next tour */
nextStep: () => void;
/** Go to the previous tour */
prevStep: () => void;
/** Options of the tour */
options: OnboardingTourOptions<T>;
}>;
/**
* This hook is used to manage onboarding tours
* You can use this hook to start, go to the next or previous tour
*
* @param tour The list of tours
* @param options The options of the tour
* @returns
*/
export declare function useOnboardingTour<T extends Record<string, unknown> = Record<string, unknown>>(tour: OnboardingTourStep<T>[], options?: OnboardingTourOptions<T>): {
readonly tour: OnboardingTourStep<T>[];
readonly currentStep: OnboardingTourStep<T> | undefined;
readonly currentStepIndex: number | undefined;
readonly selectedStepId: string | undefined;
readonly setCurrentStepIndex: (index: number) => void;
readonly startTour: () => void;
readonly endTour: () => void;
readonly skipTour: () => void;
readonly nextStep: () => void;
readonly prevStep: () => void;
readonly options: {
loop: boolean;
onOnboardingTourStart?: () => void;
onOnboardingTourEnd?: () => void;
onOnboardingTourComplete?: () => void;
onOnboardingTourSkip?: () => void;
onOnboardingTourChange?: ((tourStep: OnboardingTourStep<T>) => void) | undefined;
};
};