react-multistep-forms/dist/index.d.ts

Flexible and customizable multi-step form context for React with native React Hook Form integration.

import * as react_jsx_runtime from 'react/jsx-runtime';
import React$1, { ReactNode } from 'react';

type StepKey = string;
type MultistepFormContextType = {
    /** The index of the current step in the multistep form. */
    currentStepIndex: number;
    /** The key of the current step in the multistep form. */
    currentStepKey: StepKey;
    /** A mapping of step keys to their associated field names. */
    stepFields: Record<StepKey, string[]>;
    /** A function to update the mapping of step keys to field names. */
    setStepFields: React$1.Dispatch<React$1.SetStateAction<Record<StepKey, string[]>>>;
    /** Advances to the next step in the multistep form. */
    nextStep: () => void;
    /** Moves to the previous step in the multistep form. */
    prevStep: () => void;
    /** Submits the multistep form. */
    submit: () => void;
    /** An array of step keys derived from the `stepFields` mapping. */
    steps: StepKey[];
};
/**
 * A React context for managing the state and behavior of a multistep form.
 * Provides the current step, navigation functions, and step field mappings.
 */
declare const MultistepFormContext: React$1.Context<MultistepFormContextType | undefined>;
/**
 * A provider component for the `MultistepFormContext`.
 *
 * - Manages the state of the multistep form, including the current step and step fields.
 * - Provides functions for navigating between steps and submitting the form.
 *
 * @param {Object} props - The props for the `MultistepFormProvider` component.
 * @param {Record<StepKey, string[]>} props.stepFieldsMap - A mapping of step keys to their associated field names.
 * @param {() => void} [props.onSubmit] - An optional callback function to execute on form submission.
 * @param {ReactNode} props.children - The child elements to render within the provider.
 *
 * @returns {React.ReactElement} The `MultistepFormContext.Provider` wrapping the provided children.
 */
declare function MultistepFormProvider({ stepFieldsMap, onSubmit, children, }: {
    stepFieldsMap: Record<StepKey, string[]>;
    onSubmit?: () => void;
    children: ReactNode;
}): react_jsx_runtime.JSX.Element;

/**
 * A custom hook for accessing the `MultistepFormContext`.
 *
 * - Provides access to the current step, navigation functions, and step field mappings.
 * - Ensures that the hook is used within a `MultistepFormProvider`.
 *
 * @throws {Error} If the hook is used outside of a `MultistepFormProvider`.
 *
 * @returns {MultistepFormContextType} The context value containing the multi-step form state and functions.
 */
declare function useMultistepForm(): {
    currentStepIndex: number;
    currentStepKey: string;
    stepFields: Record<string, string[]>;
    setStepFields: React.Dispatch<React.SetStateAction<Record<string, string[]>>>;
    nextStep: () => void;
    prevStep: () => void;
    submit: () => void;
    steps: string[];
};

type MultistepFormProps = {
    /** The child elements to be rendered inside the MultistepForm container. */
    children?: React$1.ReactNode;
    /** Optional additional CSS classes to style the container. */
    className?: string;
};
/**
 * A container component for rendering a multi-step form.
 *
 * @param {MultistepFormProps} props - The props for the MultistepForm component.
 * @param {React.ReactNode} [props.children] - The child elements to render inside the container.
 * @param {string} [props.className] - Optional CSS classes for styling the container.
 *
 * @returns {React.ReactElement} A `div` element wrapping the provided children.
 */
declare function MultistepForm({ children, className }: MultistepFormProps): react_jsx_runtime.JSX.Element;

type StepProps = {
    /** The title of the step, displayed at the top. */
    title?: string;
    /** Indicates whether the step is valid. Defaults to `true`. */
    isValid?: boolean;
    /** The child elements to be rendered inside the step. */
    children: React$1.ReactNode;
    /** Optional additional CSS classes for styling the step container. */
    className?: string;
    /** If `true`, hides the title of the step. */
    hideTitle?: boolean;
};
/**
 * A component that represents a single step in a multi-step form.
 *
 * - Displays a title (if provided) and optionally hides it based on `hideTitle`.
 * - Shows a validity indicator next to the title based on the `isValid` prop.
 * - Renders the provided child elements inside the step container.
 *
 * @param {StepProps} props - The props for the Step component.
 * @param {string} [props.title] - The title of the step.
 * @param {boolean} [props.isValid=true] - Indicates whether the step is valid.
 * @param {React.ReactNode} props.children - The child elements to render inside the step.
 * @param {string} [props.className] - Optional CSS classes for styling the step container.
 * @param {boolean} [props.hideTitle] - If `true`, hides the title of the step.
 *
 * @returns {React.ReactElement} A `div` element representing the step.
 */
declare function Step({ title, hideTitle, isValid, children, className }: StepProps): react_jsx_runtime.JSX.Element;

type ProgressBarProps = {
    /** The type of progress bar to render. Can be "dot", "bar", or "dashed". */
    type: "dot" | "bar" | "dashed";
    /** Optional additional CSS classes for styling the progress bar container. */
    className?: string;
    /** The fill color for the progress bar or active segments/dots. */
    fillColor?: string;
    /** The track color for the progress bar or inactive segments/dots. */
    trackColor?: string;
    /** The height of the progress bar or dashed segments. */
    height?: string;
    /** The color of active dots in the "dot" type progress bar. */
    dotColor?: string;
    /** The color of inactive dots in the "dot" type progress bar. */
    inactiveDotColor?: string;
    /** The color of the connector between dots in the "dot" type progress bar. */
    connectorColor?: string;
    /** The size of the dots in the "dot" type progress bar. */
    dotSize?: string;
    /** The gap between dashed segments in the "dashed" type progress bar. */
    dashedGap?: string;
    /** The border radius of dashed segments in the "dashed" type progress bar. */
    dashedSegmentRadius?: string;
};
/**
 * A component that renders a progress bar for a multi-step form.
 * Supports three types: "bar", "dot", and "dashed".
 *
 * - "bar": A horizontal bar that fills based on the current step.
 * - "dot": A series of dots connected by lines, with active and inactive states.
 * - "dashed": A series of dashed segments that fill based on the current step.
 *
 * @param {ProgressBarProps} props - The props for the ProgressBar component.
 * @param {"dot" | "bar" | "dashed"} props.type - The type of progress bar to render.
 * @param {string} [props.className] - Optional additional CSS classes for styling.
 * @param {string} [props.fillColor="bg-blue-500"] - The fill color for active elements.
 * @param {string} [props.trackColor="bg-gray-300"] - The color for inactive elements.
 * @param {string} [props.height="h-2"] - The height of the progress bar or segments.
 * @param {string} [props.dotColor="bg-blue-500 border-blue-500"] - The color of active dots.
 * @param {string} [props.inactiveDotColor="bg-white border-gray-300"] - The color of inactive dots.
 * @param {string} [props.connectorColor="bg-gray-300"] - The color of the connector between dots.
 * @param {string} [props.dotSize="w-3 h-3"] - The size of the dots.
 * @param {string} [props.dashedGap="gap-1"] - The gap between dashed segments.
 * @param {string} [props.dashedSegmentRadius="rounded"] - The border radius of dashed segments.
 *
 * @returns {React.ReactElement | null} The rendered progress bar or null if the type is invalid.
 */
declare function ProgressBar({ type, className, fillColor, trackColor, height, dotColor, inactiveDotColor, connectorColor, dotSize, dashedGap, dashedSegmentRadius, }: ProgressBarProps): react_jsx_runtime.JSX.Element | null;

type StepContainerProps = {
    /** The child elements representing the steps in the multi-step form. */
    children: ReactNode;
    /** Optional additional CSS classes for styling the container. */
    className?: string;
};
/**
 * A container component for rendering the active step in a multi-step form.
 *
 * - Uses the `useMultistepForm` hook to determine the current step index.
 * - Renders only the active step based on the current step index.
 *
 * @param {StepContainerProps} props - The props for the StepContainer component.
 * @param {React.ReactNode} props.children - The child elements representing the steps.
 * @param {string} [props.className] - Optional CSS classes for styling the container.
 *
 * @returns {React.ReactElement} A `div` element containing the active step.
 */
declare function StepContainer({ children, className }: StepContainerProps): react_jsx_runtime.JSX.Element;

type ButtonProps = {
    /** The content to be displayed inside the button. */
    children: React$1.ReactNode;
    /** Optional additional CSS classes for styling the button. */
    className?: string;
    /** Optional click event handler for the button. */
    onClick?: (event: React$1.MouseEvent<HTMLButtonElement>) => void;
};

/**
 * A button component that navigates to the next step in a multi-step form.
 *
 * @param {ButtonProps} props - The props for the NextButton component.
 * @param {React.ReactNode} props.children - The content to be displayed inside the button.
 * @param {string} [props.className=""] - Additional CSS classes to style the button.
 * @param {function} [props.onClick] - Optional click handler to execute custom logic.
 *
 * @returns {React.ReactElement | null} - A button element or null if the current step is the last step.
 */
declare const NextButton: ({ children, className, onClick }: ButtonProps) => react_jsx_runtime.JSX.Element | null;

/**
 * Renders a button that navigates to the previous step in a multi-step form.
 *
 * - If `children` is a string, renders a styled button.
 * - If `children` is a React element, clones it and injects the click handler and className.
 * - If on the first step, renders nothing.
 *
 * @param {ButtonProps} props - Props for the PrevButton component.
 * @param {React.ReactNode} props.children - Button content or custom element.
 * @param {string} [props.className] - Additional CSS classes.
 * @param {(event: React.MouseEvent<HTMLButtonElement>) => void} [props.onClick] - Optional click handler.
 * @returns {React.ReactElement | null} The rendered button or null.
 */
declare const PrevButton: ({ children, className, onClick }: ButtonProps) => react_jsx_runtime.JSX.Element | null;

/**
 * Renders a button that submits the multi-step form.
 *
 * - If `children` is a string, renders a styled button.
 * - If `children` is a React element, clones it and injects the click handler and className.
 * - If not on the last step, renders nothing.
 *
 * @param {ButtonProps} props - Props for the SubmitButton component.
 * @param {React.ReactNode} props.children - Button content or custom element.
 * @param {string} [props.className] - Additional CSS classes.
 * @param {(event: React.MouseEvent<HTMLButtonElement>) => void} [props.onClick] - Optional click handler.
 * @returns {React.ReactElement | null} The rendered button or null.
 */
declare const SubmitButton: ({ children, className, onClick }: ButtonProps) => react_jsx_runtime.JSX.Element | null;

type StepControlsProps = {
    /** The child elements to be rendered inside the StepControls container. */
    children: React$1.ReactNode;
    /** Optional additional CSS classes to style the container. */
    className?: string;
};
/**
 * A container component for step control buttons in a multi-step form.
 *
 * @param {StepControlsProps} props - The props for the StepControls component.
 * @param {React.ReactNode} props.children - The child elements to render inside the container.
 * @param {string} [props.className] - Optional CSS classes for styling the container.
 *
 * @returns {React.ReactElement} A `div` element wrapping the provided children.
 */
declare function StepControls({ className, children }: StepControlsProps): react_jsx_runtime.JSX.Element;

export { MultistepForm, MultistepFormContext, MultistepFormProvider, NextButton, PrevButton, ProgressBar, Step, StepContainer, StepControls, SubmitButton, useMultistepForm };
export type { ButtonProps };