tutorial()

The exported tutorial object lets you open, advance, rewind, close, and update the active tutorial from anywhere in your app.

Open a tutorial

import { useEffect } from 'react';
import { TutorialOverlay, tutorial } from 'react-tutorial-overlay';

function App() {
  useEffect(() => {
    async function runTutorial() {
      const result = await tutorial.open({
        steps: [
          {
            targetIds: ['target-id'],
            title: 'Welcome',
            content: 'This message is plain text.',
            infoBoxAlignment: 'center',
          },
          {
            targetIds: ['target-id'],
            title: 'Focused step styling',
            content: 'This step overrides the shared tutorial styling.',
            infoBoxAlignment: 'right',
            options: {
              infoBoxWidth: '28rem',
              infoBoxMargin: 16,
              highlightBorderColor: '#f97316',
              highlightBorderRadius: 20,
              labels: {
                done: 'Ship it',
              },
            },
          },
        ],
        options: {
          highLightPadding: 12,
          infoBoxHeight: 220,
          infoBoxWidth: '24rem',
          infoBoxMargin: 24,
          overlayColor: 'rgba(15, 23, 42, 0.6)',
          highlightBorderColor: '#22c55e',
          highlightBorderRadius: 16,
          zIndex: 3000,
          labels: {
            prev: 'Back',
            next: 'Continue',
            skip: 'Dismiss',
            done: 'Finish',
          },
          keyboardNavigation: true,
          closeOnOverlayClick: true,
        },
      });

      console.log(result.reason);
    }

    runTutorial();
  }, []);

  return (
    <div>
      <TutorialOverlay />
    </div>
  );
}

Available methods

• tutorial.open({ steps, options, startAt }): opens a tutorial and starts at startAt when provided. startAt is clamped to the available step range. Returns Promise<{ reason: 'completed' | 'skipped' | 'closed' | 'replaced' }> when that tutorial ends.
• tutorial.next(): moves to the next step and closes the overlay after the last step.
• tutorial.prev(): moves back one step when possible.
• tutorial.goTo(index): moves the active tutorial to a specific step. The index is clamped to the available range, and calling it while closed is a no-op.
• tutorial.getState(): returns { open, index, stepCount, currentStep } for external progress controls.
• tutorial.close(): closes the overlay and resolves the pending tutorial.open() promise with reason: 'closed'.
• tutorial.update(index, step): replaces a step definition while the tutorial is active.

Promise result reasons

• completed: the last step was completed through tutorial.next() or the built-in 완료 button.
• skipped: the built-in 건너뛰기 button was clicked.
• closed: the tutorial was closed manually with tutorial.close(), Escape, or backdrop click.
• replaced: a newer tutorial.open() call replaced a tutorial whose promise was still pending.

Step fields

• targetIds: array of element ids to highlight for the current step.
• title: optional heading shown in the info box.
• content: optional plain text body.
• infoBoxAlignment: optional center, left, or right.
• options: optional per-step overrides for infoBoxHeight, infoBoxWidth, infoBoxMargin, highlightBorderColor, highlightBorderRadius, and partial labels.
• onPrevStep: optional callback that runs when leaving the step with tutorial.prev().
• onNextStep: optional callback that runs when leaving the step with tutorial.next().

External progress control

await tutorial.open({
  steps,
  startAt: 1,
});

tutorial.goTo(0);

const state = tutorial.getState();
console.log(state.currentStep?.title);

tutorial.goTo() only updates the active index. It does not resolve the Promise returned by tutorial.open() and does not invoke onPrevStep or onNextStep.

Tutorial options

• highLightPadding: expands the highlight frame around the target in pixels. Defaults to 8.
• infoBoxHeight: sets the default info box height in pixels and can be overridden per step.
• infoBoxWidth: sets the default info box width with a CSS length such as 360 or '24rem'. Defaults to '20rem' and can be overridden per step.
• infoBoxMargin: controls the default vertical gap between the target and the info box and can be overridden per step.
• overlayColor: sets the backdrop color. Defaults to rgba(0, 0, 0, 0.5).
• highlightBorderColor: sets the default highlight border color. Defaults to #ff0000 and can be overridden per step.
• highlightBorderRadius: sets the default highlight border radius with a CSS length. Defaults to the current padding-based radius and can be overridden per step.
• zIndex: sets the overlay stack level. Defaults to 9999.
• labels: overrides the built-in prev, next, skip, and done button labels by default and can be partially overridden per step.
• keyboardNavigation: enables Escape, ArrowLeft, and ArrowRight shortcuts while the overlay is open. Defaults to true.
• closeOnOverlayClick: closes the tutorial when the backdrop itself is clicked. Defaults to false.
• onClose: runs when the active tutorial is closed, including replacement by a newer tutorial.open() call.

Keyboard shortcuts are ignored while an input, textarea, select, or contenteditable element has focus. The info box automatically repositions itself to stay within the viewport when the target is close to an edge. Step customization resolves in this order: step.options -> tutorial options -> built-in defaults. overlayColor, highLightPadding, keyboardNavigation, closeOnOverlayClick, zIndex, and onClose stay global for the whole run. When a tutorial opens, focus moves into the labeled dialog UI and returns to the previously active element after close. The current overlay does not trap focus. onClose remains available for side effects, while the Promise returned by tutorial.open() is the async completion hook.