NebulaSlider

NebulaSlider Component

The NebulaSlider is an Astro component that turns your web content into an interactive slide presentation. It includes navigation controls, customization options, and content interaction features built with a clean, modular design.

Getting Started

Basic Usage

Simply add the component to any MDX page:

import {NebulaSlider} from 'astro-nebula-ui';

<NebulaSlider triggerText="Open Slides" title="Content Slides"/>

Configuration Options

The NebulaSlider component supports extensive configuration for different Astro site layouts and content structures beyond Starlight.

Container Selection

Control which part of your page gets converted into slides:

<!-- Default: Works with Starlight and common layouts -->
<NebulaSlider />

<!-- Custom container selector -->
<NebulaSlider containerSelector=".my-content-area" />

<!-- Multiple possible containers -->
<NebulaSlider containerSelector=".main-content, .article-body, #content" />

<!-- Custom Astro site layout -->
<NebulaSlider
  containerSelector=".post-content"
  includeStarlight={false}
/>

Slide Breaking Configuration

Customize which elements create new slides:

<!-- Default: HR elements and H1-H3 headings -->
<NebulaSlider />

<!-- Only H2 headings create slides -->
<NebulaSlider slideBreakers="h2" />

<!-- Custom class-based breaks -->
<NebulaSlider slideBreakers="h2, .slide-break, .new-slide" />

<!-- Multiple element types -->
<NebulaSlider slideBreakers="hr, h1, h2, .chapter-break" />

Content Filtering

Exclude unwanted elements from slides:

<!-- Default: Excludes scripts, styles, noscript -->
  <NebulaSlider />

<!-- Custom exclusions -->
<NebulaSlider excludeElements="script, style, .sidebar, .navigation" />

<!-- Exclude ads and widgets -->
<NebulaSlider excludeElements="script, style, .ads, .widget, .social-share" />

<!-- Minimal exclusions -->
<NebulaSlider excludeElements="script, style" />

Complete Configuration Examples

Astro Blog Layout

<NebulaSlider
  triggerText="View as Presentation"
  title="Blog Post Slides"
  containerSelector=".post-content, .article-content"
  slideBreakers="h2, h3"
  excludeElements="script, style, .share-buttons, .related-posts"
  includeStarlight={false}
  contentFilter=""
  keyboardShortcut="ctrl+alt+p"
/>

Custom Astro Documentation Site

<NebulaSlider
  triggerText="View Documentation as Slides"
  title="Documentation Slides"
  containerSelector=".docs-content, .documentation-body"
  slideBreakers="h2, .section-break"
  excludeElements="script, style, .sidebar, .toc, .edit-page"
  includeStarlight={false}
  contentFilter=""
  keyboardShortcut="ctrl+shift+d"
/>

Astro Content Collection Layout

<NebulaSlider
  triggerText="View as Slides"
  title="Content Collection Slides"
  containerSelector=".content-wrapper, .markdown-content"
  slideBreakers="h1, h2, hr, .slide-separator"
  excludeElements="script, style, .navigation, .footer"
  includeStarlight={true}
  contentFilter=""
  keyboardShortcut="ctrl+shift+s"
/>

Keyboard Shortcut Configuration

Customize the keyboard shortcut used to open the slide viewer:

<!-- Default shortcut: Ctrl+Shift+S -->
<NebulaSlider />

<!-- Custom shortcut: Ctrl+Alt+S -->
<NebulaSlider keyboardShortcut="ctrl+alt+s" />

<!-- Mac-style shortcut: Cmd+Shift+S -->
<NebulaSlider keyboardShortcut="cmd+shift+s" />

<!-- Simple Alt+S shortcut -->
<NebulaSlider keyboardShortcut="alt+s" />

<!-- Function key shortcut -->
<NebulaSlider keyboardShortcut="f9" />

Supported Modifiers:

ctrl - Control key (Windows/Linux)
cmd or meta - Command key (Mac)
alt - Alt/Option key
shift - Shift key

Examples:

"ctrl+shift+s" - Ctrl + Shift + S
"ctrl+alt+p" - Ctrl + Alt + P
"cmd+shift+s" - Cmd + Shift + S (Mac)
"alt+f" - Alt + F
"f8" - F8 key only

The shortcut is displayed in the button’s tooltip and works from anywhere on the page (except when typing in input fields).

Configuration Properties

Property	Type	Default	Description
`triggerText`	string	`"View as Slides"`	Text for the trigger button
`title`	string	`"Content Slides"`	Title for the slideshow
`containerSelector`	string	`".sl-markdown-content, main .content, article"`	CSS selector for content container
`slideBreakers`	string	`"hr, h1, h2, h3"`	Elements that create slide breaks
`excludeElements`	string	`"script, style, noscript"`	Elements to exclude from slides
`includeStarlight`	boolean	`true`	Whether to include Starlight fallback selectors
`contentFilter`	string	`""`	Additional content filtering (future use)
`keyboardShortcut`	string	`"ctrl+shift+s"`	Custom keyboard shortcut to open slides

Content Optimization

Structure your MDX content using horizontal rules (---) to create explicit slide boundaries:

---
title: My Presentation
---

# Introduction Slide
This is the first slide content.

---

# Second Slide
This is the second slide content.

---

# Third Slide
This is the third slide content.

Key Guidelines:

Use --- separators to create explicit slide breaks
One main concept per slide keep content focused and concise
Start with a clear heading on each slide for better navigation
Include visual elements like code blocks, images, and lists
Write presentation-friendly content avoid overly long paragraphs

Usage Recommendations

Verify keyboard navigation works smoothly across all features
Check theme compatibility with your site design
Optimize content length for slide format presentation
Use bookmarks to mark important slides for quick reference

Core Presentation Features

Automatic Slide Generation

The component intelligently parses your page content and creates slides based on:

Heading-based divisions Each major heading starts a new slide
Content sections Logical content breaks are preserved
Code blocks and lists Special formatting is maintained
Image and media support Visual content is properly displayed
Content filtering Automatically excludes scripts, styles, and metadata

Navigate through your presentation using multiple methods:

Keyboard shortcuts: Arrow keys, Page Up/Down, Home/End
Navigation buttons: Previous/Next slide controls
Direct slide access: Click slide counter or press G or Ctrl+G for go-to modal
Touch gestures: Mobile-friendly navigation
Progress tracking: Visual progress bar shows completion

Viewing Modes

The component offers three distinct viewing experiences:

Slide Mode: Traditional presentation view with one slide at a time
Reading Mode: Continuous document view with original content structure
Overview Mode: Thumbnail grid showing all slides at once

Advanced Search & Discovery

Real-time Search

Instant search across all slide content with debounced input
Highlighted matches with search term emphasis
Filtered results showing only relevant slides
Search persistence across different viewing modes

Advanced search interface with enhanced features:

Modal interface opened with / or F keys
Keyboard navigation through search results with arrow keys
Content snippets showing search context
Reading mode support with section-aware search

Interactive Table of Contents

Smart TOC generation based on slide headings or content structure
Slide previews with hover effects showing content summary
Reading time estimates calculated at 200 words per minute
Bookmark indicators showing saved slides with star icons
Collapsible sidebar with toggle and click-to-expand

Interactive Tools & Features

Laser Pointer System

Sophisticated annotation tool with multiple drawing modes:

Drawing Modes:

Freehand drawing : Natural sketching with smooth curves
Circle tool : Perfect circles with drag-to-resize
Rectangle tool : Rectangular shapes with drag-to-resize
Line tool : Straight lines with precise endpoints

Settings:

Color picker : Choose from any color
Thickness control : Adjustable from 1-10 pixels
Fade duration : Configurable from 0.5-5 seconds
Reverse fade : Lines can undraw from end back to start
Persistent storage : Settings saved to localStorage

Bookmark Management

Keep track of important slides:

Quick bookmarking with B key or click bookmark button
Bookmark panel with Shift+B showing all saved slides
Slide previews with slide numbers and content excerpts
Persistent storage : Bookmarks saved per page URL
Visual indicators in thumbnails, TOC, and current slide

Font Size Control

Accessibility-focused text scaling:

Dynamic font adjustment with +/- buttons
Range: 60% to 500% scaling with validation
Double-click reset on decrease button
Persistent preferences saved to localStorage

Customization & Themes

Theme System

Choose from 6 carefully designed themes with light/dark variants:

Default : Clean, minimal theme
Dracula : Popular developer-friendly purple theme
GitHub : Familiar GitHub-inspired design
Discord : Gaming-community inspired dark theme
One Dark : Atom editor’s beloved color scheme
Ocean : Blue-toned theme with calming colors

Light/Dark Theme Toggle

Independent light/dark toggle system:

Independent toggle : Works separately from Starlight’s theme
Persistent preference : State saved to localStorage
Visual feedback : Sun/moon icons indicate current state
Theme compatibility : All themes have light/dark variants

Smart Theme Compatibility

Automatic conflict resolution with Starlight themes
Persistent theme selection across sessions
Theme cycling with T keyboard shortcut
Dropdown selector with available themes

Accessibility & Keyboard Support

Comprehensive Keyboard Shortcuts

Opening Slideshow

Ctrl+Shift+S - Open slide viewer (default, configurable)
Custom shortcuts supported via keyboardShortcut prop

← → - Previous/Next slide
Page Up Page Down - Previous/Next slide
Home - Go to first slide
End - Go to last slide
G or Ctrl+G - Open go-to slide modal

Search & Tools

/ or F - Open search modal
↑ ↓ - Navigate search results (in modal)
Enter - Select search result
L - Toggle laser pointer
S - Open laser pointer settings
T - Cycle through themes
B - Bookmark current slide
Shift + B - Toggle bookmarks panel

General

Esc - Close slideshow/modal/panel
Shift + ? - Show keyboard help modal

Accessibility Features

ARIA live regions for screen reader announcements
Keyboard focus management with proper tab order and focus trapping
Screen reader optimized labels and descriptions
High contrast support across all themes
Semantic HTML structure for assistive technologies

Technical Implementation

Performance Optimizations

Lazy content loading for smooth performance
Debounced search to prevent excessive operations
Throttled scroll listeners for efficient updates
Local storage caching for user preferences
Efficient DOM manipulation with minimal reflows

Browser Compatibility

Modern ES6+ JavaScript with module support
CSS Grid and Flexbox for responsive layouts
Local Storage API for preference persistence
Canvas API for laser pointer functionality
Fullscreen API for immersive presentations

Image Example

Houston