A simple Stimulus controller and a helper that enables you to show a guided tour overlay on your website. It requires Bootstrap to be installed and have Popover loaded.
This gem comes with the npm package @itsbede/guided-tour (package repo) that is installed and included into your apps app/javascript/controller/application.js by running the installer.
This gem is built for Rails apps (>= 7.1) using stimulus and esbuild (with jsbundling).
- Add to your Gemfile:
gem 'guided_tour'
- Run installer
./bin/rails g guided_tour:install
In your view
<!-- this is the example markup of you page that you want to guide the user through -->
<ul>
<li id="foo">Foo</li>
<li id="bar">Bar</li>
<li id="baz">Baz</li>
</ul>
<!-- this is the gems helper code -->
<%= guide_through(t('home.guide')) %>
<!-- if you like to go hardcoded you can hand in the map directly -->
<%= guide_through(
{ foo: "This is explanation for the element with the html id foo",
bar: "This is explanation for the element with the html id bar",
baz: "This is explanation for the element with the html id baz" }
) %>In your locale .yml
# config/locales/en.yml
---
en:
# ...
home:
guide:
foo: This is explanation for the element with the html id foo
bar: This is explanation for the element with the html id bar
baz: This is explanation for the element with the html id baz
# ...You can customize the header and the navigation buttons of the popover by defining this keys in your locale .yml
en:
guided-tour:
next-btn-text: "Your custom Next button text"
prev-btn-text: "Your custom Back button text"
done-btn-text: "Your custom Done button text"
step-line: "Step {{current}} of {{total}}"
de:
guided-tour:
next-btn-text: "Weiter"
prev-btn-text: "Zurück"
done-btn-text: "Fertig"
step-line: "Erklärung {{current}} von {{total}}"Make sure to include {{current}} and {{total}} in your step-line key to have the progress of the tour shown.
This is the default styling from the package that is inserted into the pages <head></head>.
.guided-tour--overlay {
box-shadow: rgb(233 77 77 / 80%) 0 0 1px 2px,
rgb(84 84 84 / 50%) 0 0 0 5000px;
box-sizing: content-box;
position: absolute;
border-radius: 4px;
transition: all .3s ease-out;
z-index: 9998;
pointer-events: none;
opacity: 0;
}
.guided-tour--starter-btn-wrapper {
position: absolute;
right: 1rem;
bottom: 1rem;
animation: slideFromRight 1.2s cubic-bezier(0.23, 1, 0.32, 1) forwards;
animation-delay: 1s;
/* Ensures button is hidden before animation starts */
opacity: 0;
/* Improve animation performance */
will-change: transform, opacity;
> .btn {
/* Prevent any layout shifts during animation */
transform-origin: right center;
z-index: 1000; /* Ensure button stays above other content */
}
}
.guided-tour--overlay.active {
opacity: 1;
}
.guided-tour--popover {
z-index: 9999;
max-width: 33.3%;
}You can override the default styles by using these CSS classes. Keep in mind that this package is meant to be used with bootstrap.
The gem is available as open source under the terms of the MIT License.