Lightweight User Tour/Onboarding Library for Web Apps – CodingIntroJS

CodingIntroJS is a lightweight JavaScript library that creates guided, interactive tours for websites.

It highlights specific DOM elements with a spotlight effect and attaches descriptive tooltips to guide your users through a feature or an entire page.

Features:

• Spotlight Highlighting: Focuses user attention by blurring the background and highlighting a specific element.
• Customizable Tooltips: You can control the colors, text, and titles of the tour pop-ups.
• Keyboard Accessibility: Users can navigate the tour with arrow keys.
• Localization: All button and tooltip labels are fully customizable for different languages.
• Dynamic Content: Tooltip titles and content can be generated from functions. This is useful for tours that need to display data from the highlighted element itself.
• Callback Hooks: Provides hooks like onStart, onFinish, and onBeforeStep for running your own code at key moments in the tour’s lifecycle.

How To Use It:

1. Download the zip and load the codingintrojs.min.js script in the document.

<script src="src/codingintrojs.min.js"></script>

2. Make sure your target HTML elements have proper selectors. The library works with any valid CSS selector:

<h1 id="welcome">CodingIntroJS</h1>
<p class="lead">Your Super-Easy Guide to Interactive Website Tours</p>
<button id="example">An Example Button</button>

3. Create an array of step objects. Each object tells the tour what to highlight and what to display.

• selector (string): The CSS selector for the element to highlight. The tour will skip the step if the element is not found or is not visible.
• isWelcome (boolean): If true, this step becomes a full-screen welcome message. No selector is needed.
• title (string | function): The text for the tooltip’s title. It can be a function that receives the highlightedElement to generate dynamic text.
• content (string | function): The main text for the tooltip’s body. It can also be a function for dynamic content.
• className (string): An optional CSS class added to the tooltip for custom styling on a per-step basis.
• condition (function): A function that receives the highlightedElement. If it returns false, the step is skipped.
• welcomeImage (string): A URL for an image to display on a welcome (isWelcome: true) step.
• welcomeButtonText (string): Custom text for the main button on a welcome step, overriding the global default.
• welcomeButtonIcon (string): A custom emoji or text icon for the welcome step button.
• highlightBorderRadius (string): A specific CSS border-radius value (e.g., '10px') for the highlight overlay, overriding the default behavior which mimics the element’s own radius.

const steps = [
  {
    isWelcome: true, // Welcome screen
    title: 'Welcome!',
    content: "Welcome to our website",
    welcomeImage: '/path/to/welcome.png',
    welcomeButtonText: "Get Started!" 
  },
  {
    selector: '#welcome',
    title: 'Welcome Header',
    content: 'This is the main title of the page.',
    className: 'custom-class',
    condition: (element) => element.dataset.active === 'true'
  },
  {
    selector: '.lead',
    title: 'Intro',
    content: 'CodingIntroJS description.'
  },
  {
    selector: '#example',
    title: 'Example Button',
    content: 'This is a button',
    highlightBorderRadius: '50%' 
  }
];

4. Instantiate CodingIntroJS with your steps and an optional configuration object.

const myTour = new CodingIntroJS(steps, {
  // options here
});

5. Start the tour wheneve you need.

myTour.start();

6. All possible configuration options:

• defaultTheme (string): Sets the visual theme for the tour. Can be 'dark' (default) or 'light'.
• allowClose (boolean): If false, disables the ability for users to close the tour with the ESC key. Defaults to true.
• animationSpeed (number): The duration of the spotlight and tooltip animations in milliseconds. Defaults to 150.
• animationEasing (string): The CSS easing function for animations (e.g., 'ease-in-out'). Defaults to 'ease-out'.
• backdropColor (string): The CSS color of the overlay behind the highlighted element. Defaults to 'rgba(15, 22, 36, 0.9)'.
• highlightPadding (number): The amount of padding in pixels around the highlighted element. Defaults to 8.
• keyboardNavigation (boolean): Enables or disables navigation using keyboard arrow keys. Defaults to true.
• scrollPadding (number): Extra padding in pixels when an element is scrolled into view, useful for avoiding fixed headers. Defaults to 40.
• safeAreaPadding (number): The minimum distance in pixels between the tooltip and the edge of the screen. Defaults to 10.
• labels.prev (string): Text for the “Previous” button.
• labels.next (string): Text for the “Next” button.
• labels.finish (string): Text for the “Finish” button on the last step.
• labels.of (string): Text used in the progress indicator (e.g., “1 of 5″).
• labels.welcomeTitle (string): Default title for welcome screens.
• labels.welcomeContent (string): Default content for welcome screens.
• labels.welcomeButton (string): Default button text for welcome screens.
• icons.prev (string): An emoji or text to use as the “Previous” button icon.
• icons.next (string): An emoji or text to use as the “Next” button icon.
• icons.finish (string): An emoji or text to use as the “Finish” button icon.

const myTour = new CodingIntroJS(steps, {
  defaultTheme: 'dark',
  allowClose: false,
  animationSpeed: 300,
  animationEasing: 'ease-in-out',
  backdropColor: 'rgba(15, 22, 36, 0.9)',
  highlightPadding: 8,
  keyboardNavigation: true,
  scrollPadding: 40,
  safeAreaPadding: 10,
  labels: {
    prev: 'Previous',
    next: 'Next',
    finish: 'Finish',
    of: 'Of',
    welcomeTitle: 'Welcome!',
    welcomeContent: 'Welcome Content',
    welcomeButton: 'Welcome Button'
  },
  icons: {
    prev:"◀️",
    next:"▶️",
    finish:"✅"
  },
});

7. Callback functions (hooks):

• onStart (function): A function that runs when the tour begins.
• onFinish (function): A function that runs only when the tour is completed via the “Finish” button.
• onExit (function): A function that runs when the tour is closed before completion (e.g., with the ESC key or by calling .exit()).
• onBeforeStep (function): A function that runs before each step is displayed. It receives the index and step object as arguments.
• onAfterStep (function): A function that runs after each step is displayed. It receives the index, step object, and the highlightedElement as arguments.

const myTour = new CodingIntroJS(steps, {
  onStart: () => {
    // do something
  },
  onFinish: () => {
    // do something
  },
  onExit: () => {
    // do something
  },
  onBeforeStep: (index, step) => {
    console.log(`About to show step ${index}:`, step.selector || 'Welcome Screen');
  },
  onAfterStep: (index, step, highlightedElement) => {
    console.log(`Just showed step ${index}. Highlighted:`, highlightedElement);
  }
});

8. API methods.

• start(): Initiates or restarts the tour from the beginning.
• next(): Advances to the next step in the sequence.
• prev(): Returns to the previous step.
• goTo(index): Jumps directly to a specific step by index.
• exit(): Terminates the tour immediately and cleans up DOM elements.
• finish(): Completes the tour and triggers the onFinish callback.
• setTheme(theme): Switches between ‘dark’ and ‘light’ themes during runtime.
• getCurrentStep(): Returns the current step object for inspection.

FAQs:

Q: Can CodingIntroJS handle dynamically generated content?
A: Yes, through several mechanisms. The title and content properties accept functions that receive the highlighted element, allowing you to generate content based on current DOM state. Additionally, the onBeforeStep callback lets you modify the page before each step displays.

Q: What happens if a target element doesn’t exist or isn’t visible?
A: The library skips the step and logs a warning to the console. This prevents tours from breaking when elements are conditionally rendered or hidden. You can use the condition property to implement custom visibility logic for more control.

Q: How do I customize the styles beyond the built-in themes?
A: CodingIntroJS uses CSS custom properties that you can override in your stylesheet. The className property on individual steps allows targeted styling. For extensive customization, you can modify the backdrop color, highlight padding, and animation properties through the configuration object.

Related Resources:

• 10 Best Tour Plugins To Guide Visitors Through Your App

The post Lightweight User Tour/Onboarding Library for Web Apps – CodingIntroJS appeared first on CSS Script.