Gatsby Plugin NProgress

Gatsby Plugin NProgress automatically displays a page loading progress indicator using the accessible-nprogress library when page navigation is delayed. The plugin integrates seamlessly with Gatsby's browser APIs to provide visual feedback during page transitions that exceed one second.

Package Information

• Package Name: gatsby-plugin-nprogress
• Package Type: npm (Gatsby Plugin)
• Language: JavaScript
• Installation: npm install gatsby-plugin-nprogress

Core Imports

This is a Gatsby plugin that is configured in gatsby-config.js rather than imported directly. The plugin exports are used internally by Gatsby's plugin system.

The plugin internally exports these Gatsby browser API hooks:

// Internal exports (used by Gatsby, not directly imported)
export { onClientEntry, onRouteUpdateDelayed, onRouteUpdate } from "gatsby-plugin-nprogress/gatsby-browser";

Basic Usage

// In your gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-nprogress`,
      options: {
        // Setting a color is optional.
        color: `tomato`,
        // Disable the loading spinner.
        showSpinner: false,
      },
    },
  ],
}

Architecture

The plugin implements Gatsby's browser API hooks to manage the progress indicator lifecycle:

• Client Initialization: onClientEntry injects CSS styles and configures the progress library
• Progress Start: onRouteUpdateDelayed activates the progress bar when navigation is slow
• Progress Complete: onRouteUpdate hides the progress bar when navigation finishes
• Styling System: Dynamic CSS injection with customizable colors and animations
• Accessibility: Uses accessible-nprogress library for screen reader compatibility

Capabilities

Plugin Configuration

Configure the progress indicator appearance and behavior through gatsby-config.js options.

/**
 * Plugin configuration options extending accessible-nprogress options
 * @typedef {Object} PluginOptions
 * @property {string} [color="#29d"] - CSS color value for the progress bar and spinner
 * @property {boolean} [showSpinner] - Whether to display the loading spinner
 * @property {number} [minimum] - Minimum progress percentage (0.0 to 1.0)
 * @property {string} [easing] - CSS easing string for progress animation
 * @property {number} [speed] - Animation speed in milliseconds
 * @property {boolean} [trickle] - Whether progress should trickle
 * @property {number} [trickleSpeed] - Trickle speed in milliseconds
 * @property {string} [parent] - Custom parent element selector
 * @property {string} [template] - CSS template for progress bar
 */

Usage Example:

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-nprogress`,
      options: {
        color: `#ff6347`,
        showSpinner: false,
        minimum: 0.2,
        easing: 'ease',
        speed: 200,
        trickle: true,
        trickleSpeed: 200,
      },
    },
  ],
}

Client Entry Hook

Initializes the progress indicator by injecting CSS styles and configuring the accessible-nprogress library.

/**
 * Gatsby browser API hook called when the client-side app starts
 * @param {Object} gatsbyApi - Gatsby API object (unused by this plugin)
 * @param {PluginOptions} [pluginOptions={}] - Configuration options from gatsby-config.js
 */
function onClientEntry(gatsbyApi, pluginOptions = {}) {
  // Implementation details handled by Gatsby
}

This function:

• Merges default options with user-provided plugin options
• Injects comprehensive CSS styles for the progress bar, spinner, and animations
• Configures the accessible-nprogress library with the merged options
• Adds styles for both regular and custom parent container scenarios

Route Update Delayed Hook

Starts the progress indicator when route navigation is delayed beyond one second.

/**
 * Gatsby browser API hook called when route update is delayed
 * Automatically called by Gatsby when page navigation takes longer than 1 second
 */
function onRouteUpdateDelayed() {
  // Implementation details handled by Gatsby
}

This function calls NProgress.start() to display the progress bar, providing immediate user feedback during slow page transitions.

Route Update Hook

Completes and hides the progress indicator when route navigation finishes.

/**
 * Gatsby browser API hook called when route update completes
 * Automatically called by Gatsby when page navigation finishes
 */
function onRouteUpdate() {
  // Implementation details handled by Gatsby
}

This function calls NProgress.done() to hide the progress bar and reset the indicator state.

Default Configuration

/**
 * Default configuration options applied if not overridden
 * @constant {Object} defaultOptions
 * @property {string} color - Default progress bar color
 */
const defaultOptions = { color: "#29d" };

CSS Styling

The plugin automatically injects comprehensive CSS styles including:

• Progress Bar: Fixed position bar at the top of the viewport with customizable color
• Progress Peg: Animated trailing effect with glow shadow
• Loading Spinner: Top-right corner spinner with rotation animation
• Custom Parent Support: Styles for progress indicators within specific containers
• Animations: Smooth CSS keyframe animations for spinner rotation

All colors are dynamically set based on the color option, ensuring consistent theming throughout the progress indicator components.