Appearance
Using Spotlight Overlay for Guided Tours
This guide shows you how to use the useSpotlightOverlay composable to create guided tours and feature highlights in your Vue 3 applications.
Overview
The Spotlight Overlay composable helps you:
- Create onboarding tours for new users
- Highlight new features
- Guide users through complex workflows
- Focus attention on specific UI elements
Setup
First, add the Spotlight Overlay component to your app root (App.vue or Provider.vue). Import OSpotOverlay component and add it to your template.
Basic Usage
Highlight a Single Element
Use setInstructionBarConfigByElementId() to highlight a single element by its ID. Provide the element ID, arrow position, and configuration with title, content, and button callback.
Creating Multi-Step Tours
Simple Tour
Create multi-step tours by calling setInstructionBarConfigByElementId() for each step. Use callbacks to navigate between steps and reset the tour when complete.
Tour with Custom Highlighting
You can highlight a different element than the one with the instruction bar by using the elementToHighLightId option.
Tour with Element Click Action
Configure tours to automatically click elements when the user interacts with the tour button.
Arrow Positions
Available arrow positions:
'top'- Arrow points up'bottom'- Arrow points down'left'- Arrow points left'right'- Arrow points right'leftTop'- Arrow on left, aligned to top'leftBottom'- Arrow on left, aligned to bottom'RightTop'- Arrow on right, aligned to top'RightBottom'- Arrow on right, aligned to bottom
Available Methods
| Method | Description |
|---|---|
setInstructionBarConfigByElementId(options) | Highlight element by ID with instruction bar |
setInstructionBarConfig(options) | Set instruction bar with custom position |
resetInstructionBarConfig() | Reset and close spotlight |
highlightElement({ elementId, className }) | Add highlight class to element |
Use Cases
1. Onboarding Tours
- Guide new users through the application
- Introduce key features and functionality
- Show users where to find important tools
2. Feature Highlights
- Highlight new features after updates
- Draw attention to recently added functionality
- Announce new capabilities
3. Workflow Guidance
- Guide users through complex multi-step processes
- Help users complete forms correctly
- Show users how to use advanced features
4. Contextual Help
- Provide help when users are stuck
- Show tips for better usage
- Explain feature benefits
5. Product Tours
- Showcase product capabilities
- Demonstrate key workflows
- Highlight important UI elements
Best Practices
- Keep tours short - 3-5 steps maximum to avoid overwhelming users
- Allow skipping - Always provide a way to skip or close the tour
- Save tour state - Remember if user has seen the tour using localStorage
- Smooth transitions - Add small delays between steps for better UX
- Clear instructions - Use concise, actionable content
- Test on different screens - Ensure tours work on mobile and desktop
- Highlight correctly - Make sure element IDs exist before highlighting
📖 Related Documentation: