JavaScript Navigation API

Interactive navigation controller providing responsive behavior, mobile menu support, sticky navigation, and smooth scrolling with hash-based navigation state management.

Global API Access

The ThemeNav functionality is available globally in browsers:

// Global browser objects
window.SphinxRtdTheme = {
    Navigation: ThemeNav,  // Main navigation controller
    StickyNav: ThemeNav    // Legacy alias for backwards compatibility
}

ThemeNav Class

Core navigation controller that manages responsive navigation behavior, mobile menu interactions, and scroll-based navigation updates.

Constructor and Initialization

function ThemeNav(): NavigationController

Creates a new navigation controller instance with internal state management for scroll position, window dimensions, and navigation elements.

Internal State:

• navBar: Navigation sidebar element
• win: Window object reference
• winPosition: Current scroll position
• winHeight: Window height in pixels
• docHeight: Document height in pixels
• isRunning: Initialization state flag

Core Methods

enable

enable(withStickyNav?: boolean): void

Enables theme navigation functionality with optional sticky navigation behavior.

Parameters:

• withStickyNav (boolean, optional): Enable sticky navigation scrolling (default: true)

Actions:

• Initializes DOM event handlers via init()
• Sets up window scroll monitoring for sticky navigation
• Configures window resize handling
• Establishes hash change navigation reset
• Prevents multiple initialization calls

Usage Example:

// Enable with sticky navigation (default)
SphinxRtdTheme.Navigation.enable();

// Enable without sticky navigation  
SphinxRtdTheme.Navigation.enable(false);

enableSticky

enableSticky(): void

Legacy method that enables navigation with sticky behavior. Maintained for backwards compatibility with theme version 0.3.0.

Usage Example:

// Legacy sticky navigation enablement
SphinxRtdTheme.StickyNav.enableSticky();

init

init($: jQuery): void

Initializes navigation with jQuery DOM manipulation and event handlers.

Parameters:

• $ (jQuery): jQuery instance for DOM operations

Setup Actions:

• Identifies navigation sidebar (div.wy-side-scroll:first)
• Configures mobile menu toggle handlers
• Sets up navigation link click handlers
• Implements responsive table wrapping
• Adds expand/collapse buttons to nested navigation
• Manages current page highlighting and navigation state

reset

reset(): void

Resets navigation state based on current URL hash, expanding navigation to show the current page.

Behavior:

• Extracts anchor from window.location.hash
• Finds corresponding navigation link in sidebar
• Expands navigation hierarchy to reveal current page
• Handles fallback navigation for missing anchors
• Scrolls current navigation item into view
• Manages ARIA accessibility attributes

Scroll and Resize Handling

onScroll

onScroll(): void

Handles window scroll events to maintain sticky navigation behavior. Updates navigation scroll position to keep current content visible.

Functionality:

• Calculates new navigation position based on window scroll
• Prevents navigation scrolling beyond document bounds
• Synchronizes navigation scroll with window scroll position
• Uses requestAnimationFrame for smooth performance

onResize

onResize(): void

Handles window resize events to recalculate dimensions for responsive navigation behavior.

Updates:

• Window height (winHeight)
• Document height (docHeight)
• Navigation positioning calculations

Navigation State Management

hashChange

hashChange(): void

Manages navigation state during hash-based navigation (anchor links). Prevents scroll interference during programmatic navigation.

Behavior:

• Sets linkScroll flag during hash changes
• Temporarily disables scroll handlers
• Restores scroll handling after navigation completes

toggleCurrent

toggleCurrent(elem: jQuery): void

Toggles the current navigation item state and manages navigation hierarchy expansion/collapse.

Parameters:

• elem (jQuery): Navigation element to toggle

Actions:

• Removes 'current' class from sibling navigation items
• Toggles current item's expanded/collapsed state
• Updates ARIA accessibility attributes (aria-expanded)
• Manages nested navigation visibility
• Preserves terminal navigation elements (items without children)

DOM Event Handlers

The navigation system automatically sets up the following event handlers:

Mobile Menu Toggle

// Mobile navigation menu toggle
$("[data-toggle='wy-nav-top']").click() 
// Toggles: $("[data-toggle='wy-nav-shift']").toggleClass("shift")

Navigation Link Clicks

// Navigation menu item clicks
$(".wy-menu-vertical .current ul li a").click()
// Actions: Close mobile menu, toggle current item, handle hash change

Version Selector Toggle

// Version/language selector toggle
$("[data-toggle='rst-current-version']").click()
// Toggles: $("[data-toggle='rst-versions']").toggleClass("shift-up")

Responsive Table Enhancement

// Automatic responsive table wrapping
$("table.docutils:not(.field-list,.footnote,.citation)")
    .wrap("<div class='wy-table-responsive'></div>");

// Special handling for footnote and citation tables
$("table.docutils.footnote")
    .wrap("<div class='wy-table-responsive footnote'></div>");
$("table.docutils.citation")
    .wrap("<div class='wy-table-responsive citation'></div>");

Cross-Browser Compatibility

RequestAnimationFrame Polyfill

The navigation includes a complete polyfill for smooth animation across all browsers:

// Polyfills for older browsers
window.requestAnimationFrame = function(callback, element): number
window.cancelAnimationFrame = function(id: number): void

Supports vendor prefixes: ms, moz, webkit, o with fallback to setTimeout-based implementation.

Usage Examples

Basic Navigation Setup

// Standard theme navigation initialization
$(document).ready(function() {
    SphinxRtdTheme.Navigation.enable();
});

Custom Navigation Configuration

// Navigation with custom scroll behavior
$(document).ready(function() {
    var nav = SphinxRtdTheme.Navigation;
    
    // Enable without sticky behavior for custom control
    nav.enable(false);
    
    // Custom scroll handler
    $(window).on('scroll', function() {
        // Custom scroll logic
        nav.onScroll();
    });
});

Mobile-First Navigation

// Responsive navigation with mobile detection
$(document).ready(function() {
    var isMobile = $(window).width() <= 768;
    
    // Enable sticky navigation only on desktop
    SphinxRtdTheme.Navigation.enable(!isMobile);
    
    // Additional mobile-specific handlers
    if (isMobile) {
        // Custom mobile navigation behavior
    }
});

Integration with Custom Scroll Events

// Integration with custom scrolling libraries
$(document).ready(function() {
    SphinxRtdTheme.Navigation.enable();
    
    // Trigger navigation reset after custom scroll events
    $('.custom-scroll-trigger').on('click', function() {
        // Perform custom scrolling
        $('html, body').animate({scrollTop: target}, 500, function() {
            // Reset navigation state after scroll
            SphinxRtdTheme.Navigation.reset();
        });
    });
});

Module Exports

For Node.js/CommonJS environments:

module.exports.ThemeNav = ThemeNav();

The exported ThemeNav is a pre-instantiated navigation controller ready for use.