LiveJoyride

A guided tour component for Phoenix LiveView applications. Create interactive step-by-step tours to onboard users or highlight features.

Features

• Pure Elixir/LiveView implementation - no external JS dependencies
• Customizable styling via Tailwind CSS classes
• Spotlight effect highlights target elements
• Responsive tooltip positioning
• Progress tracking (step X of Y)
• Back/Next/Done navigation

Installation

Add live_joyride to your dependencies in mix.exs:

def deps do
  [
    {:live_joyride, "~> 0.1.0"}
  ]
end

Then add the JavaScript hook to your app.js:

import { Joyride } from "live_joyride"

let liveSocket = new LiveSocket("/live", Socket, {
  hooks: { Joyride, ...otherHooks }
})

If you installed via Hex, the JS is at:

import { Joyride } from "../deps/live_joyride/assets/js"

Usage

1. Mark target elements

Add data-joyride attributes to elements you want to highlight:

<div data-joyride="welcome-section">
  Welcome to our app!
</div>

<button data-joyride="submit-btn">Submit</button>

2. Add the component to your LiveView

<.live_component
  module={LiveJoyride.Component}
  id="tour"
  steps={[
    %{target: "welcome-section", title: "Welcome!", content: "This is where we greet you."},
    %{target: "submit-btn", title: "Submit", content: "Click here when you're done."}
  ]}
  run={@show_tour}
/>

3. Handle tour completion

def handle_info({:tour_complete, "tour"}, socket) do
  {:noreply, assign(socket, show_tour: false)}
end

Customization

Override default styles by passing a classes map:

<.live_component
  module={LiveJoyride.Component}
  id="tour"
  steps={@steps}
  run={@show_tour}
  classes={%{
    overlay: "bg-black/50",
    spotlight: "border-4 border-blue-500 rounded-lg",
    tooltip: "bg-white border border-gray-200 rounded-xl shadow-xl p-0",
    titlebar: "",  # Empty string hides the titlebar
    title: "text-lg font-bold text-gray-900",
    content: "text-sm text-gray-600",
    footer: "border-t border-gray-200 pt-3 mt-4",
    progress: "text-sm text-gray-500",
    button: "px-4 py-2 rounded border",
    button_primary: "bg-blue-500 text-white border-blue-500",
    button_back: "bg-white text-gray-700 border-gray-300",
    close: "w-4 h-4 rounded-full bg-red-500"
  }}
/>

Available class keys

Default Style

The default styling is inspired by classic Mac OS - a retro look with black borders and gradient backgrounds. Override with modern Tailwind classes as shown above.

License

MIT License - see LICENSE file.