react-tour-callout

A simple library to create UI callouts designed for building custom tour components

This component provides a simple way to build a callout targeted at any UI element on the page.

It's worth noting up front that this library is not designed to replace the popular (and powerful) react-joyride library. The goal of this library is to provide a more primitive (and less opinionated) way to build a single callout against any UI element.

In my experience, react-joyride is primarily optimized for building a single linear tour on a page. However, in many cases, tour callouts are displayed more progressively over multiple pages and often only when certain features are interacted with. This makes building these "one-off" tour callouts more challenging since you either need to manage the tour cycle manually or even use multiple tour instances. Advanced UI customization can also be a challenge beyond the built-in properties and often requires custom CSS to target built-in styles.

In contrast, this library handles the positioning of the callout but leaves it up to the developer to manage the tour lifecycle and layout/styling within the callout.

Features

• ✅ Anchor the callout to any element on the page via a ref or CSS selector. The Popper library is used to accomplish this.
• ✅ Optionally render a "speech bubble" arrow that based on its position relative to the anchored element. The color/positioning of this arrow can be customized as well.
• ✅ Optionally render a semi-transparent backdrop behind the callout.
• ✅ Highlight multiple elements above the backdrop (not just the anchor element). Custom styles can also be applied to highlighted elements.
• ✅ Allow highlighted elements to be interactive or read only to the user.

Installation

npm install --save react-tour-callout

Using the demo

1. Checkout this repository

2. Run the below command to start the server on port 3010.

npm run example

Docs

Props

| Prop | Type | Default | Definition | |------------------|---------------------------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | open | boolean | REQUIRED | Whether to open the callout popover | | height | number | REQUIRED | Height of the popover in px | | width | number | REQUIRED | Width of the popover in px | | showBackdrop | boolean | true | Whether to show the backdrop when the popover is open | | backdropProps | BackdropProps | None | Additional props to pass onto the backdrop component | | placement | PopoverPlacement | center | REQUIRED | See the Popper docs for available options | | zIndex | number | 1500 | The z-index value to apply to the popover | | popoverMargin | number | None | Add a margin to the popover container (y-axis for right/left placement, x-axis for top/bottom placement) | | popoverAnchor | HTMLElement | string | null | null | The element to anchor the popover to. Can specify either the element ref or a selector that resolves to the element. If null is provided, the popover is centered on the page. | | anchorOffset | [number, number] | None | Adjust the position of the popover relative to the anchor in the format [skidding, distance]. See the Popper docs for more information. | | raiseAnchor | boolean | true | Whether to increase the z-index of the target element to "raise" it above the backdrop | | enterTransition | boolean | true | Whether to enable a "zoom in" animation when opening the popover | | showArrow | boolean | true | Whether to show a speech bubble like arrow pointing at the anchor element | | arrowOffset | number | None | Offset in px to adjust arrow position by on its primary axis | | arrowColor | string | #000 | Color of the arrow icon using CSS color syntax | | highlightTargets | (HTMLElement | string)[] | None | Array of elements (selector or ref) to raise above the backdrop. This can be used to "highlight" multiple elements on the page for a single tour step. | | highlightStyles | CSSProperties | None | Additional CSS styles to apply to highlighted elements | | children | React.ReactNode | REQUIRED | The body of the callout popover |

Example

This is just a simple contrived example showing anchoring the popover to a button.

export const App = () => {
    const [open, setOpen] = React.useState(false);

    return (
        <div>
            <button
                className="open-button"
                onClick={() => setOpen(true)}
            >
                Open popover
            </button>
            <CalloutPopover
                placement="bottom"
                open={open}
                height={180}
                width={350}
                showBackdrop={true}
                backdropProps={{
                    onClick: () => setOpen(false),
                    onEsc: () => setOpen(false),
                }}
                popoverAnchor=".open-button"
            >
                <h1>Popover content here...</h1>
                <button
                    onClick={() => setOpen(false)}
                >
                    Close popover
                </button>
            </CalloutPopover>
        </div>
    )
};

Note

Feel free to submit issues/PR's and I will do my best to respond. I'm sure there are plenty of improvements that can be made :-)

License

This project is licensed under the terms of the MIT license.