Foundation
Jump to Nav

# Magellan

JavaScript

Magellan allows you to create navigation that tracks the active section of a page your user is in. Pair it with our Sticky plugin to create a fixed navigation element.

## Setup

You can use Magellan with any navigation element, like our Menu or your own custom component. Just add the attribute `data-magellan` to the container, and links to specific sections of your page. Each section needs a unique ID.

    <ul class="horizontal menu" data-magellan>
      <li><a href="#first">First Arrival</a></li>
      <li><a href="#second">Second Arrival</a></li>
      <li><a href="#third">Third Arrival</a></li>
    </ul>
    <div class="sections">
      <section id="first" data-magellan-target="first">First Section</section>
      <section id="second" data-magellan-target="second">Second Section</section>
      <section id="third" data-magellan-target="third">Third Section</section>
    </div>

## Sticky Navigation

You can use Magellan with our Sticky plugin to create a persistent navigation header or sidebar.

This first example is a simplified version of the table of contents on the right side of this page:

    <div class="large-3 columns" data-sticky-container>
      <nav class="columns sticky" data-sticky data-anchor="exampleId" data-sticky-on="large">
        <ul class="vertical menu" data-magellan>
          <li><a href="#first">First Arrival</a></li>
          <li><a href="#second">Second Arrival</a></li>
          <li><a href="#third">Third Arrival</a></li>
        </ul>
      </nav>
    </div>

This example is the menu bar floating at the top of the page.

    <div data-sticky-container>
      <div class="sticky" id="example" data-sticky data-margin-top="0" style="width:100%;" data-margin-bottom="0" data-top-anchor="topAnchorExample" data-btm-anchor="bottomOfContentId:bottom">
        <nav data-magellan>
          <ul class="horizontal menu expanded">
          <li><a href="#first">First Arrival</a></li>
          <li><a href="#second">Second Arrival</a></li>
          <li><a href="#third">Third Arrival</a></li>
          </ul>
        </nav>
      </div>
    </div>

## JavaScript Reference

### Initializing

The file `foundation.magellan.js` must be included in your JavaScript to use this plugin, along with `foundation.core.js`.

### Foundation.Magellan

Creates a new instance of Magellan.

    var elem = new Foundation.Magellan(element, options);

Fires these events: Magellan#event:init

Name | Type | Description
--- | --- | ---
`element` | Object | jQuery object to add the trigger to.
`options` | Object | Overrides to the default plugin settings.

### Plugin Options

Use these options to customize an instance of Magellan. Plugin options can be set as individual data attributes, one combined `data-options` attribute, or as an object passed to the plugin's constructor. Learn more about how JavaScript plugins are initialized.

Name | Type | Default | Description
--- | --- | --- | ---
`data-animation-duration` | `number` | `500` | Amount of time, in ms, the animated scrolling should take between locations.
`data-animation-easing` | `string` | `linear` | Animation style to use when scrolling between locations. Can be `'swing'` or `'linear'`.
`data-threshold` | `number` | `50` | Number of pixels to use as a marker for location changes.
`data-active-class` | `string` | `active` | Class applied to the active locations link on the magellan container.
`data-deep-linking` | `boolean` | `false` | Allows the script to manipulate the url of the current page, and if supported, alter the history.
`data-bar-offset` | `number` | `0` | Number of pixels to offset the scroll of the page on item click if using a sticky nav bar.

### Events

These events will fire from any element with a Magellan plugin attached.

Name | Description
--- | ---
`update.zf.magellan` | Fires when magellan is finished updating to the new active element.

### Methods

#### calcPoints

    $('#element').foundation('calcPoints');

Calculates an array of pixel values that are the demarcation lines between locations on the page. Can be invoked if new elements are added or the size of a location changes.

#### scrollToLoc

    $('#element').foundation('scrollToLoc', loc);

Function to scroll to a given location on the page.

Name | Type | Description
--- | --- | ---
`loc` | String | a properly formatted jQuery id selector. Example: '#foo'

#### reflow

    $('#element').foundation('reflow');

Calls necessary functions to update Magellan upon DOM change

#### destroy

    $('#element').foundation('destroy');

Destroys an instance of Magellan and resets the url of the window.