Gumshoe Documentation

If your navigation menu has multiple levels, you can enable nested support. When enabled, Gumshoe applies an active class to the parent list items of the currently active link.

Set nested: true and optionally provide a nestedClass name in the configuration object.

var spy = new Gumshoe('#my-awesome-nav a', {
	nested: true,
	nestedClass: 'active-parent'
});

If your site has a fixed header, you can use the offset setting to prevent the active state from triggering too early.

The offset option accepts:

• A number (static offset).
• A function that returns a number (dynamic offset).

Using a function is preferred if you need to calculate the header's height dynamically.

// Get the header
var header = document.querySelector('#my-header');

// Initialize Gumshoe with dynamic offset
var spy = new Gumshoe('#my-awesome-nav a', {
	offset: function () {
		return header.getBoundingClientRect().height;
	}
});

If your content layout changes based on the viewport (e.g., responsive design changes that alter element positions), you must enable reflow to allow Gumshoe to update its internal calculations.

Set reflow: true in the configuration object. This is disabled by default.

var spy = new Gumshoe('#my-awesome-nav a', {
	reflow: true
});

The Gumshoe instance exposes the following methods:

• setup(): Performs all necessary background calculations. Call this if you dynamically add navigation items to the DOM after initialization.
• detect(): Manually triggers the detection logic to activate the link corresponding to the content currently in the viewport.
• destroy(): Destroys the current Gumshoe instance.

If events is set to true (the default), Gumshoe emits two custom events that bubble up from the list item:

• gumshoeActivate: Emitted when a link becomes active.
• gumshoeDeactivate: Emitted when a link is no longer active.

The event.detail object contains:

• link: The anchor element.
• content: The content element.
• settings: The settings used for the current instantiation.

// Listen for activate events
document.addEventListener('gumshoeActivate', function (event) {

	// The list item
	var li = event.target;

	// The link
	var link = event.detail.link;

	// The content
	var content = event.detail.content;

}, false);

When instantiating new Gumshoe(selector, options), you can pass the following settings:

To use Gumshoe, instantiate the Gumshoe constructor by passing a CSS selector for your navigation items and an optional options object. The constructor automatically initializes the scrollspy, detects the currently active content, and attaches scroll event listeners.

Note: The navigation items must use hash links (e.g., <a href="#section-id">) that correspond to the id of the content elements you want to track.

// Example initialization
var gumshoe = new Gumshoe('.nav-item', {
  navClass: 'is-active',
  contentClass: 'is-active'
});

The Gumshoe constructor returns an object containing the following public methods:

• setup(): Manually triggers the setup process, which queries the DOM for navigation items and maps them to their corresponding content elements via their hash links.
• detect(): Manually triggers the detection of the currently active content based on the scroll position.
• destroy(): Cleans up the instantiation by deactivating the current item, removing window event listeners (scroll and optionally resize), and resetting internal variables.

var gumshoe = new Gumshoe('.nav-link');

// Manually trigger detection
gumshoe.detect();

// Clean up and remove event listeners
gumshoe.destroy();