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).
gem 'guided_tour'
./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.
FAQs
Unknown package
We found that guided_tour demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Malicious Nx npm versions stole secrets and wallet info using AI CLI tools; Socket’s AI scanner detected the supply chain attack and flagged the malware.
Security News
CISA’s 2025 draft SBOM guidance adds new fields like hashes, licenses, and tool metadata to make software inventories more actionable.
Security News
A clarification on our recent research investigating 60 malicious Ruby gems.