Motia Tutorial Driver

A lightweight Tutorial Driver used and built by Motia.

Installation

pnpm add @motiadev/tutorial-driver

Add the CSS to your project

Make sure you add the CSS to the root of your project.

import '@motiadev/tutorial-driver/tutorial.css'

Or use it in your index.css file.

@import '@motiadev/tutorial-driver/tutorial.css';

Usage

import { Tutorial, useTutorialEngine } from '@motiadev/tutorial-driver'

const steps: TutorialStepConfig[] = [
  {
    title: 'Test Tutorial',
    description: () => <div>This is a test tutorial</div>,
  },
]

export const TestTutorial = () => {
  const engine = useTutorialEngine({ steps })
  return <Tutorial engine={engine} />
}

Properties on TutorialStepConfig

TutorialStepConfig defines the configuration for a single tutorial step in the tutorial sequence. Below are the properties you can use:

| Property | Type | Required | Description | | ------------- | --------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | title | string | Yes | The header text to show for this step. | | description | React.FC<void> | Yes | A React functional component that renders the content of this tutorial step. | | image | { height: number, src: string } | No | (Optional) An image to display within the step. The object should contain height (in pixels) and src (URL string for the image source). | | link | string | No | (Optional) A URL to provide for additional information or a related action. Appears as a link in the step. | | selector | string or XPath | No | (Optional) An XPath or string selector pointing to the element this step is associated with or highlights. | | before | TutorialAction[] | No | (Optional) An array of actions (such as simulated clicks or custom callbacks) to perform before this step displays. |

Example

const steps: TutorialStepConfig[] = [
  {
    // this is going to show the title of the step
    title: 'Welcome',

    // this is going to show the content of the step
    description: () => <div>Start your journey!</div>,

    // this is going to show an image in the step
    image: { height: 120, src: '/images/tutorial-start.png' },

    // this is going to show a link to the tutorial documentation
    link: 'https://product-docs.example.com/tutorial',

    // this is going to highlight the button with the class 'start-tutorial'
    selector: xpath('button').attr('class', 'start-tutorial'),

    // this is going to click the button with the class 'show-intro' before the step is displayed
    before: [{ type: 'click', selector: xpath('button').attr('class', 'show-intro') }],
  },
  // ...more steps...
]

See type definitions for TutorialAction and XPath for advanced usage.

Selectors

This library uses XPath to select elements, but it comes with a fluent API to make it easier to use for most cases.

Examples of selectors:

Select tags by attribute

• xpath('img').attr('class', 'logo')
• xpath('img').attr('class', 'logo react')
• xpath('button').attr('class', 'btn-counter')
• xpath('button').attr('data-testid', 'test-id')

Select tags by text

• xpath('p').textContains('Click on the Vite and React logos to learn more')

Select tags by attribute containing

• xpath('img').attrContains('class', 'logo')
• xpath('button').attrContains('class', 'btn')

Overriding Styles

You can override the styles of the tutorial by using the following CSS variables.

:root {
  --tutorial-border-color: rgb(65, 65, 65);
  --tutorial-text-color: rgb(240, 240, 240, 0.8);
  --tutorial-code-bg: rgb(24, 24, 24, 0.4);
  --tutorial-code-text: rgb(240, 240, 240, 1);
  --tutorial-background: rgb(24, 24, 24, 1);

  --tutorial-accent-color: rgb(0, 115, 255);
  --tutorial-accent-color-hover: rgb(0, 145, 255);
  --tutorial-accent-color-text: rgb(255, 255, 255);
  --tutorial-accent-color-text-hover: rgb(255, 255, 255);

  --tutorial-muted-foreground: rgb(140, 140, 143);

  --tutorial-shadow: 0 10px 15px -3px var(--tw-shadow-color, #0000001a), 0 4px 6px -4px var(--tw-shadow-color, #0000001a);
  --base-font-size: 14px;
}