:camera: streamlit-tour

A Driver.js integration for Streamlit - add beautiful, interactive guided tours to your Streamlit apps with a single Python call.

Features

• :link: Bind tour steps to any Streamlit widget by its key
• :window: Element-free info steps - show contextual popups not anchored to any component
• :white_check_mark: One-time tours - automatically skip tours the user has already completed (via localStorage)
• :leftwards_arrow_with_hook: State feedback - know exactly when a tour was finished, dismissed, or skipped
• :art: Configurable - control overlay opacity, animations, progress indicators, and popover alignment

Installation

pip install streamlit-tour

Or in a more modern way:

uv add streamlit-tour

Quickstart

import streamlit as st
from streamlit_tour import Tour

st.title("My App")
st.text_input("Name", key="name_input")

tour = Tour(
    steps=[
        Tour.bind("name_input", title="Your Name", desc="Enter your name here."),
        Tour.info(title="That's it!", desc="You're ready to go."),
    ]
)

tour.start()

Usage

Tour.start()

Launches the tour. Call this inside any conditional block (e.g. a button click) or make sure to specify one_time_tour=True.

Tour.result

Stores a TourStatus object with the tour's current state:

Tour.bind()

Attaches a tour step to a Streamlit widget via its key.

Tour.bind(
    key="my_widget_key",        # Must match the widget's key= argument
    title="Step Title",
    desc="Step description text.",
    side="bottom",              # "top" | "bottom" | "left" | "right" (optional)
    align="center",             # "start" | "center" | "end" (optional)
)

How it works: Tour.bind resolves the widget using Streamlit's .st-key-<key> CSS class, which is automatically injected on any widget that has a key= argument.

Tour.info()

Creates a floating step with no element anchor - useful for introductory or summary slides.

Tour.info(
    title="Welcome!",
    desc="This tour will walk you through the main features of this app.",
)

One-Time Tour

Set one_time_tour=True to automatically skip the tour for users who have already seen it. Completion is tracked in the browser's localStorage using the tour's key.

Tour.start(
    steps=[...],
    one_time_tour=True,
    key="onboarding_tour",   # Must be unique and stable across reruns
)

To reset the tour (e.g. for testing), clear localStorage in your browser's DevTools, or use a different key.

Check out example.py file for a complete example of usage.

Tips

• Always provide a key when using one_time_tour=True or when you have multiple tours on the same page.
• Widgets must have a key= argument for Tour.bind() to locate them. Anonymous widgets (no key) are not bindable.
• Re-triggering a tour: Change the key value between Streamlit reruns to force the tour to restart.
• Column layouts: Use side and align on Tour.bind() to control which side the popover appears on narrow widgets.

Roadmap / Possible Improvements

• Better output - make the Tour returns an object instead of a simple dict
• Tabs and Pages - make the Tour navigate between tabs and pages (maybe with an intermediate Python actions ?)
• Tour.reset() - a utility function to clear the one-time-tour flag from localStorage
• Step grouping - define multiple named tours and selectively launch them
• Theme support - CSS variable overrides to match Streamlit's light/dark mode
• Driver.js parameters - implement all the other Driver.js options