/ember-scroll-to

Animated scrolling to a specified id.

Primary LanguageJavaScriptMIT LicenseMIT

ember-scroll-to

Animated vertical scrolling to a specified id.

Installation

From within your ember-cli project directory:

ember install ember-scroll-to

The component

The {{scroll-to}} creates an <a> element that, when clicked, scrolls to the specified selector.

In your template:

{{scroll-to href='#faq' label='FAQ'}}

You can also use the block form:

{{#scroll-to href='#faq'}}
  FAQ
{{/scroll-to}}

If you want to perform some action after scroll:

{{scroll-to href='#faq' afterScroll='customAction'}}

The component accepts the following options

  • href -- (required) a selector of an element to scroll to on click.
  • label -- text to display on the component. Ignored when used in a block form.
  • duration -- number of milliseconds for the transition to occur over. Default is 750ms.
  • easing -- the jQuery animate transition to use. Default is 'swing'. With a standard setup, you could also use 'linear'. If you want more, check out jQuery UI.
  • offset -- An optional offset. The most common use case for this is if you have a fixed header that you need to account for.

Example usage with all options at once:

{{scroll-to
  href='#faq'
  label='FAQ'
  duration=1000
  easing='linear'
  offset=-60
}}

Service

You can also invoke scrolling programmatically. To do so, inject the scroller service into your object:

scroller: Ember.inject.service()

Then you can use the scrollVertical method on it:

this.get('scroller').scrollVertical(target, options);

target can be anything that jQuery accepts (selector, element, jQuery collection...).

options is a hash with any of the following key-value pairs (all optional):

  • offset
  • duration
  • easing
  • complete -- a callback to execute once the scrolling animation is complete.

The method returns a Promise that will resolve as soon as the animation has completed.

Configuration

Some frameworks - like Google's Material Design Lite - will use a custom DOM structure to wrap the main content (e.g. for facilitating responsive design, modal overlays). For use in such environments, you'll want to override the default scrollable element (html, body) with the container element that should be used by the service to set the vertical scroll position. To do so, extend the service:

// app/services/scroller.js
import Ember from 'ember';
import Scroller from 'ember-scroll-to/services/scroller';

export default Scroller.extend({
  scrollable: Ember.computed(function() {
    return Ember.$('main.mdl-layout__content');
  })
});

Where in this example main.mdl-layout__content is the content container of the page for Material Design Lite. Inspect your DOM to find the main element if scrolling is not working.