Onboard

Guide users through the initial steps of using your product

Use the onboard function to guide your users through the initial steps of using your product, service, or application in an interactive way. Using the function can improve user experience, increase your engagement and steamline guidance. To test the onboard function, click on the button below.

Start onboarding

Features

You can:

• Use as many characters in your tooltips as needed
• Change the position of your tooltip
• Use HTML tags inside your tooltips
• Attach event listeners

Adapting highlight

The border-radius of your highlight will adapt to your element.

Trigger actions

Previous Next

---
import { Button, Sheet } from 'webcoreui/astro'
---


<Button className="start">Start onboarding</Button>
<Sheet
    className="onboard-modal flex justify-center sm"
    position="bottom"
    closeOnEsc={false}
    closeOnOverlay={false}
>
    <Button disabled={true} className="prev">Previous</Button>
    <Button className="next">Next</Button>
</Sheet>

<script>
    import { closeModal, get, modal, on } from 'webcoreui'
    import { onboard } from '@utils'


    const steps = [{
        element: 'h1',
        tooltip: 'You can attach tooltips with query selectors.',
        tooltipPosition: 'bottom-right'
    }, { ... }, { ... }]

    const prev = get('.prev') as HTMLButtonElement
    const next = get('.next') as HTMLButtonElement


    const onboarding = onboard(steps, {
        onEnd() {
            closeModal('.onboard-modal')

            prev.disabled = true
            next.innerText = 'Next'
        },
        onPrev(step) {
            console.log('prev to', step)
        },
        onNext(step) {
            console.log('next to', step)
        }
    })


    modal({
        trigger: '.start',
        modal: '.onboard-modal',
        onClose() {
            onboarding.end()
        }
    })


    on('.start', 'click', () => onboarding.start())


    on(prev, 'click', () => {
        onboarding.prev()

        if (!onboarding.getStep()) {
            prev.disabled = true
        }

        next.innerText = onboarding.getStep() === steps.length - 1
            ? 'Finish'
            : 'Next'
    })


    on(next, 'click', () => {
        if (onboarding.getStep() === steps.length - 1) {
            closeModal('.onboard-modal')

            prev.disabled = true
            next.innerText = 'Next'
        }

        next.innerText = onboarding.getStep() === steps.length - 2
            ? 'Finish'
            : 'Next'

        onboarding.next()

        prev.disabled = onboarding.getStep() === 0
    })
</script>

The onboarding can be created with any UI element. In this example, we use the Sheet component to handle the onboarding steps.

1. The first step is to create the UI elements that you want to use to handle onboarding. Depending on your project, this part might differ. In our case, we use a Sheet component.
2. The first step of actually using the onboard function is creating the steps. The steps are represented by an array of objects. Each step is attached to an HTML element using query selectors. Each object can have the following properties:

type Steps = {
    element: string
    tooltip: string
    tooltipPosition?: 'top-left'
        | 'top-right'
        | 'bottom-left'
        | 'bottom-right'
}[]

3. Instantiate the onboard function and pass the steps array as the first argument. The onboard function also accepts a second parameter which is the configuration object. In our case, we define three callback function:
   • onEnd: Executed when the onboarding ends. In this example, we close the modal and reset the previous/next button states.
   • onPrev: Executed when onboard.next is called.
   • onNext: Executed when onboard.prev is called.

That configuration object can also have the following other properties:

type OnboardConfig = {
    boxPadding?: number
    textPadding?: number
    endOnOverlayClick?: boolean
    endOnEsc?: boolean
    onStart?: () => void
    onEnd?: (step: Steps[0]) => void
    onPrev?: (step: Steps[0]) => void
    onNext?: (step: Steps[0]) => void
}

4. The onboarding is ended with onboarding.end when the modal is closed.
5. When the user clicks on the .start button, we can start the onboarding using the onboarding.start method.
6. When the previous button is clicked, we can call onboarding.prev to regress back to the previous step defined in the steps array. Note that we can use onboarding.getStep to get the current step index and use that to execute additional code, such as disabling the previous button or updating the “Next” button text.
7. When the next button is clicked, we can call onboarding.next to progress to the next step. Using onboarding.getStep we can find out if the user is at the last step. In this case, we can close the modal and reset the buttons. Note that we don’t need to call onboarding.end to end the onboarding. This is automatically handled when the first or last step is reached.

Accessibility

• The onboard function comes with many built-in accessibility features. Onboarding is automatically ended when the user clicks on the overlay or hits the Esc button. These functions can be disabled if necessary using the endOnOverlayClick and endOnEsc props on the configuration object.
• The active step is also automatically scrolled into viewport if its not visible when the step is reached. The tooltip and highlight is also repositioned if the size of the viewport changes, making it work responsively across all devices.
• You can change the padding of the highlight and adjust the position of the tooltip using the boxPadding and textPadding props.

API

type Steps = {
    element: string
    tooltip: string
    tooltipPosition?: 'top-left'
        | 'top-right'
        | 'bottom-left'
        | 'bottom-right'
}[]

type OnboardConfig = {
    boxPadding?: number
    textPadding?: number
    endOnOverlayClick?: boolean
    endOnEsc?: boolean
    onStart?: () => void
    onEnd?: (step: Steps[0]) => void
    onPrev?: (step: Steps[0]) => void
    onNext?: (step: Steps[0]) => void
}

const onboard: (data: Steps, config?: OnboardConfig) => {
    start: () => void
    end: () => void
    next: () => void
    prev: () => void
    getStep: () => number
}