Ctrlk
Github RepoDiscord
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Customise The Wizard

Give your new users a personalized onboarding experience with Wizarr's powerful wizard system. Create custom welcome flows that guide users through setting up their media apps, understanding your server, and more.

Overview

Wizarr's wizard system supports multiple approaches for creating and managing onboarding steps:

  1. Database-backed steps (recommended) - Create and manage steps through the admin interface

  2. Pre-invite and post-invite categories - Show steps before or after users accept invitations (Learn more)

  3. Wizard bundles - Custom sequences of steps for specific invitation types

  4. Multi-server wizards - Automatic flows for invitations covering multiple servers

  5. Legacy file-based steps - Markdown files as fallback (still supported)

1 · Managing Wizard Steps Through the Admin Interface

Accessing the Wizard Admin

Navigate to Settings → Wizard in your Wizarr admin panel to manage wizard steps and bundles.

Creating Default Steps

Default steps are server-type specific and will be shown to all users invited to that server type.

  1. Click "Default Steps" in the wizard settings

  2. Click "Create Step" to add a new step

  3. Select the server type: plex, jellyfin, emby, audiobookshelf, romm, or komga

  4. Write your content using Markdown

  5. Set conditional display (optional) using the requires field

Step Fields

  • Server Type: Which media server this step applies to

  • Category: When to show this step - "Before Invite Acceptance" (pre-invite) or "After Invite Acceptance" (post-invite)

  • Title: Optional override for the step heading

  • Markdown: The main content of your step

  • Requires: Comma-separated setting keys that must be truthy for the step to display

  • Require Interaction: When enabled, users must click a link or button in the step before they can proceed to the next step

New Feature: The Category field allows you to control whether steps are shown before or after users accept invitations. Learn more about pre-invite and post-invite steps.

Conditional Step Display

Use the requires field to show steps only when certain conditions are met:

This step will only show if both discord_url and enable_notifications settings have truthy values.

2 · Wizard Bundles (Custom Flows)

Wizard bundles allow you to create completely custom onboarding sequences that can be assigned to specific invitations.

Creating a Bundle

  1. Click "Custom Bundles" in the wizard settings

  2. Click "Create Bundle"

  3. Name your bundle (e.g., "VIP Onboarding", "Family Setup")

  4. Add a description (optional)

  5. Create and assign steps to your bundle

Bundle Steps

Bundle steps are different from default steps:

  • No server type - they're not tied to a specific media server

  • Flexible ordering - drag and drop to reorder steps within the bundle

  • Custom content - can include any markdown content you want

  • Interaction requirements - can also be configured to require user interaction

Assigning Bundles to Invitations

When creating an invitation, you can:

  1. Select a wizard bundle from the dropdown

  2. Leave it as "Automatic" to use the default server-type steps

3 · Multi-Server Wizard Flows

For invitations that cover multiple media servers, Wizarr automatically creates a combined wizard flow.

How It Works

  1. User accepts invitation for multiple servers

  2. Wizard automatically combines steps from each server type

  3. Steps are shown in order based on server type (alphabetical)

  4. User progresses through all relevant steps

Server Types Supported

  • Plex - Media streaming server

  • Jellyfin - Open-source media server

  • Emby - Media server platform

  • Audiobookshelf - Audiobook and podcast server

  • Romm - ROM and game library manager

  • Komga - Comic and manga library server

4 · Writing Effective Wizard Steps

Markdown Syntax

Wizarr supports standard Markdown with some enhancements:

Styling Options

  • Links as buttons: Add {.btn} to make links look like buttons

  • External links: Add {:target="_blank"} to open in new tab

  • Images: Use standard Markdown syntax with optional classes

  • Tailwind classes: Add {.class-name} for custom styling

Recently Added Media Carousel

Use the recently_added_media widget to show the posters of the newest items on the media server:

The widget reads the newest items of each library. Then it sorts all the items by the date they were added, newest first, and shows the first items. Thus one library cannot fill the carousel.

  • libraries (optional): the names of the libraries to show, with commas between them. Case does not matter. A name that is not on the server gives no items. If you do not set libraries, the widget uses the libraries that are enabled in Wizarr for the server. If Wizarr has no library list for the server, the widget uses all the libraries.

  • limit (optional): the maximum number of posters. The default is 6.

The Add... → Recently Added Media menu item in the wizard-step editor inserts this syntax for you.

Plex Collection Carousel

For Plex wizard steps, use the collection_media widget to show posters from a named collection:

The collection name is matched case-insensitively across the Plex server's libraries. The optional limit parameter caps the number of posters and defaults to 15. Set it to 0 to show the entire collection. The Add... → Collection Media menu item in the wizard-step editor inserts this syntax for you.

Templates in Shared Bundles

You can import and export third-party bundles. Wizarr stores their content and applies the same rendering rules to imported and edited steps.

Wizarr renders step templates in a Jinja sandbox. A template cannot read Python internals or run commands on the server.

Templates can use server_name, server_type, server_url, external_url, and the application settings, for example discord_id or overseerr_url. The same values are available through settings, for example settings.server_name. Wizarr does not give templates settings with credential names (passwords, tokens, secrets, and API keys), sessions, or Python objects.

You can use the usual Jinja features: conditions, loops, set, with, macros, filters, and string methods. For translations, use {{ _("Welcome") }}, {{ _("Welcome to %(name)s", name=server_name) }}, or {% trans %}...{% endtrans %}. url_for is available for links to Wizarr pages and static files.

Cards, buttons, and media widgets remain available. For example:

Templates cannot include, import, or extend other templates, and cannot use recursive loops. Wizarr also stops a template that runs too many loop iterations or function calls, or that makes very large text. Wizarr shows a step error when this occurs.

Wizarr shows the HTML in a step as you write it, including styles, scripts, and iframes. Titles display as plain text. Before you import a bundle from a third party, read its steps: their HTML and scripts run in the wizard for each invited user.

Requiring User Interaction

You can force users to engage with step content before allowing them to proceed to the next step. This is useful for ensuring users actually download apps, read important information, or acknowledge terms.

How It Works

  1. Enable "Require Interaction" when creating or editing a step in the admin interface

  2. Add interactive elements like links or buttons to your step content

  3. Users must click on at least one link or button before the "Next" button becomes enabled

Example Step Content

Visual Feedback

  • Disabled Next Button: Appears dimmed with reduced opacity until interaction occurs

  • Visual Indicators: The button shows "not-allowed" cursor when hovered

  • Automatic Enable: As soon as the user clicks any link or button, the Next button becomes active

5 · Legacy File-Based Steps (Fallback)

While the database-backed approach is recommended, Wizarr still supports file-based steps as a fallback.

File Structure

File-Based Front Matter

When Files Are Used

  • No database steps exist for the server type

  • Database is unavailable (during migrations, etc.)

  • Fallback behavior ensures the wizard always works

6 · Access Control

Wizard Access Control

By default, wizard access is restricted to:

  • Authenticated users (logged-in admins)

  • Users with valid invitation codes (stored in session)

Disabling Access Control

Set the wizard_acl_enabled setting to false to allow unrestricted access to the wizard.

Visitors Without Access

When a visitor opens /wizard/ or a wizard step without access, Wizarr shows a help page at /wizard/help. It does not show the admin login.

  • If Protect Wizard Access is on, the help page tells the visitor to open the link from their invitation. It does not show wizard steps.

  • If Protect Wizard Access is off, the help page has a link to the wizard steps of each server type. Thus you can send /wizard/ to users who want to read the steps again after they sign up.

7 · Previewing and Testing

Preview Options

  1. Click "Preview" button when editing steps

  2. Visit /wizard while logged in to test the full flow

  3. Use invitation links to test the user experience

Testing Multi-Server Flows

  1. Create an invitation for multiple servers

  2. Use the invitation link to test the combined flow

  3. Verify step order and content display

8 · Advanced Features

Step Ordering

  • Database steps: Automatically ordered by position

  • File-based steps: Ordered alphabetically (use 01_, 02_ prefixes)

  • Bundle steps: Drag and drop to reorder

Dynamic Content

Steps can reference server settings and configuration:

Conditional Logic

Use the requires field to show steps conditionally:

Only shows if discord_url is set in the requires field.

9 · Best Practices

Content Guidelines

  • Keep steps concise - users want to get started quickly

  • Use clear calls-to-action - make buttons and links obvious

  • Test on mobile - many users will access on phones

  • Include screenshots - visual aids help understanding

  • Use interaction requirements wisely - only require interaction for critical steps like app downloads or terms acceptance

Step Organization

  • Start with essentials - app download, account setup

  • End with optional content - advanced features, tips

  • Use logical progression - each step builds on the previous

  • Consider user journey - think about what they need when

Bundle Strategy

  • Create specific bundles for different user types

  • VIP users might get extended onboarding

  • Family members might need simpler instructions

  • Power users might want advanced configuration steps

10 · Migration from File-Based Steps

If you're upgrading from an older version with file-based steps:

  1. Database steps take precedence - they'll be used if they exist

  2. File-based steps remain as fallback

  3. Import existing files through the admin interface

  4. Gradually migrate to database-backed approach

  5. Test thoroughly before removing file-based steps

11 · Troubleshooting

Common Issues

Problem
Solution

Steps not showing

Check server type matches invitation

Wrong step order

Verify position values in database

Missing steps

Check requires field conditions

Bundle not working

Verify bundle assignment on invitation

Next button won't enable

Ensure step has interactive elements (links/buttons) and interaction requirement is properly configured

Debug Tips

  1. Check admin logs for wizard-related errors

  2. Verify database connectivity for step loading

  3. Test with different server types to isolate issues

  4. Use browser dev tools to inspect step loading

12 · FAQ

Question
Answer

Can I disable the wizard entirely?

Yes, don't create any steps and remove existing ones

Do I need to know HTML/CSS?

No, Markdown is sufficient for most use cases

Can I use custom JavaScript?

Not directly, but you can use interactive Markdown elements

How do I backup my wizard steps?

Export through the admin interface or backup your database

Can I preview changes before publishing?

Yes, use the preview button in the step editor

That's it! 🎉

Wizarr's wizard system gives you complete control over your user onboarding experience. Whether you use simple default steps or create elaborate custom bundles, your users will have a smooth, guided introduction to your media server.

Start with the admin interface, create your first step, and watch your users get set up faster than ever before! ✨

PreviousDiscord Integration
NextPassword and Passkey Recovery

Last updated