Top

Usage

A stalker can automatically update a target based on the position of the scrollbar and the monitoring of markers within the page. This is especially useful for navigation items that need to update based on the content currently in view. Take the following for example.

<div class="wrapper">
    <aside id="nav">
        <a href="#one">First</a>
        <a href="#two">Second</a>
        <a href="#three">Third</a>
    </aside>

    <section id="articles">
        <article id="one">...</article>
        <article id="two">...</article>
        <article id="three">...</article>
    </section>
</div>

What we want to do is update the navigation items when an article is scrolled into view. We can instantiate a stalker using the targets in the navigation, and the markers in the articles list.

$('body').stalker({
    target: '#nav a',
    marker: '#articles article'
});

Markers and targets will be matched based on the value of the targetBy and markBy options. By default this matches the ID of the marker against the href of the target.

Overflow Containers

A stalker can also monitor an element that has overflow auto. Simply pass the overflown element as the constructor.

$('#overflown').stalker({
    ...
});

Notes

  • The active target will have an .is-active class added.
  • The marker in view will have an .is-stalked class added.
  • Markers and targets can be placed anywhere in the page.
Top

Options

Inherits all options from the parent Component.

Option Type Default Description
onlyWithin bool true Whether to activate or deactivate a target while within a marker. If disabled, the target will stay activated even after leaving the marker.
marker string CSS selector for elements to mark and monitor during page scroll.
markBy string id The HTML attribute on the marker to match against the target.
target string CSS selector for elements to update when a marker is reached.
targetBy string href The HTML attribute on the target to match against the marker.
threshold int 50 The distance in pixels between the viewport edge and the marker to trigger activation.
throttle int 50 The number of milliseconds to throttle all scrolling events.
Top

Events

Inherits all events from the parent Component.

Event Arguments Description
activating element:marker, element:target Triggered before a marker is entered and a target is activated.
activated element:marker, element:target Triggered after a marker is entered and a target is activated.
deactivating element:marker, element:target Triggered before a marker is exited and a target is deactivated.
deactivated element:marker, element:target Triggered after a marker is exited and a target is deactivated.
scroll Triggered every page scroll after markers have been processed.
Top

Properties

Inherits all properties from the parent Component.

Property Type Description Found With
container element The element to monitor scroll events on. If the element has overflow auto, it will be the constructor element, else it will be the window.
markers collection A collection of marker elements to monitor and notify against. marker option
offsets array A list of top and left offsets for all markers. These offsets are used for monitoring the scroll.
targets collection A collection of target elements to activate. target option
Top

Methods

Inherits all methods from the parent Component.

Method Description
activate(element:marker) Manually set the active target based on the marker. Is automatically called through scroll monitoring events.
deactivate(element:marker) Manually remove the active target based on the marker. Is automatically called through scroll monitoring events.
refresh() Refresh the target and marker collections, and re-calculate offsets. Should rarely need to be called.