jQuery ScrollAppear Plugin

What is jQuery ScrollAppear?

jQuery ScrollAppear is a powerful and agile content appear on scroll (or on other event triggers) plugin for jQuery. jQuery ScrollAppear expands on the basic scroll appear functionality to include:

• History of what has been shown as result of the plugin;
• Ability to revert part/all of what has been shown;
• Ability to directly show elements without the user having to trigger a monitored event;
• Ability to prevent mass scroll/appear of content by setting a timeout between events (in a similar fashion to hoverIntent);
• Set a pixel offset for your trigger element;
• Set the number of event triggers to be performed before the event is unbound.

jQuery ScrollAppear is both JSLint and JSHint compliant.

How to use it?

In it’s simplest form:

$('.itemone').ScrollAppear({
    ElementAffect: '.itemtwo',
    AddClass: 'itemthree'
});

• itemone: Used to check if the element is currently viewable in the viewport;
• itemtwo: What will be shown/hidden;
• itemthree: The class that will be added to itemtwo.

A-Z parameter list

• AddClass [required]
• Callback Since 1.0.5
• DelayEffect
• EffectDuration
• ElementEffect [required]
• ElementsToShow (Number of elements to be displayed)
• NumberOfScrolls
• GatherAfterTrigger
• PixelOffset
• Timeout
• TriggerIntent
• TriggerType

AddClass [required]

The default class added will be scrollshow. Multiple classes can be added in the following fashion:

AddClass : 'classname-zero classname-one'

This parameter leverages the built-in jQuery api method .addClass.

Callback

A callback function triggered each time new elements are shown.

Callback : function (state) {
    alert("New elements have been shown");
    console.log(state.elementsToShow);
    console.log(state.numberOfElements);
    console.log(state.timesFired);
});

The callback function also passes in a state variable which you can read to get the current state of the ScrollAppear plugin (since 1.0.6).

• elementsToShow {array} – All remaining elements that are waiting to be displayed by the ScrollAppear plugin.
• numberOfElements {number} – Depending on GatherAfterTrigger, this will display the number of elements remaining.
• timesFired {number} – The number of times ScrollAppear has been fired.

DelayEffect

Default value is 0 and hence no delay is applied. Change this value to add a delay to each animation.

DelayEffect : 400

EffectDuration

Default value is set to 'fast'. This parameter can be either a number or a string as specified in the jQuery Animate Duration parameter documentation.

Numeric value

DelayEffect : 400

String value

DelayEffect : "slow"

ElementAffect [required]

Pass in the class of the elements that will be modified when the event is triggered.

ElementAffect : ".hiddenElement"

ElementsToShow

This parameter is used to determine how many elements to show (ElementAffect) when the plugin determines that itemone is in the viewport. This parameter only accepts a number.

ElementsToShow : 5

GatherAfterTrigger

Boolean value. Set to false by default so as to not update the DOM after each time ScrollAppear is triggered, this will make the plugin faster. Note, ScrollAppear automatically monitors the DOM for changes and gathers all eligible elements after each change. GatherAfterTrigger has a primary impact on the Callback state.numberOfElements property.

      GatherAfterTrigger: true

NumberOfScrolls

This is used to constrain how many times the plugin will successfully execute. Default is set to 100. Only accepts a number value.

      NumberOfScrolls: 20

PixelOffset

This can be used to refine when the trigger point for itemone by setting an offset. By setting a negative value the element will need to be visible plus the offset before the event will trigger. By setting a positive offset, the event will trigger before the element is visible plus the offset. Only accepts a number value, no “px” required.

Default value is set to 0.

PixelOffset : 200

Timeout

Used to set how long between monitoring the trigger event. A higher number is generally preferred to prevent mass triggering of the event which can cause undesirable strain on the browser if you have a significant number of hidden elements.

Accepts a number, default is 1000.

Timeout : 2000

TriggerIntent

Set to true by default. This value is used to determine if the plugin should check to see if itemone is in the viewport again after being triggered.

TriggerIntent : false

TriggerType

Accepts a string, default is "scroll". Refer to the following pages in the jQuery API for complete set of options:

• jQuery Browser Events
• jQuery Keyboard Events
• jQuery Mouse Events

TriggerType : "scroll"

A-Z Method List

• BindEvent
• Destroy
• HideElements
• ResetCounter
• ShowElements
• UnbindEvent

BindEvent

The example below will bind the event to all DOM event types specified when the plugin was initialised. Refer to TriggerType.

jQuery(this).ScrollAppear('BindEvent');

An example of calling the meothd with a DOM event type specified.

jQuery(this).ScrollAppear('BindEvent', 'scroll');

Destroy

This method will remove the instance of the plugin from the page.

jQuery(this).ScrollAppear('Destroy');

HideElements

This will hide elements that have been shown as result of jQuery ScrollAppear.

It can be called in two ways:

1. Removing the last iteration of elements shown
2. Removing a specified number of elements shown by the plugin

Option 1
Option 1 gets the last iteration count from the ElementsToShow parameter.

jQuery(this).ScrollAppear('HideElements');

Option 2

jQuery(this).ScrollAppear('HideElements', 4);

ResetCounter

This will reset the NumberOfScrolls parameter back to 0.

jQuery(this).ScrollAppear('ResetCounter');

ShowElements

This will show the next iteration of elements, allowing you to bypass the event triggers that are in place.

jQuery(this).ScrollAppear('ShowElements');

UnbindEvent

The example below will unbind the event to all DOM event types specified when the plugin was initialised. Refer to TriggerType.

jQuery(this).ScrollAppear('UnbindEvent');

An example of calling the meothd with a DOM event type specified.

jQuery(this).ScrollAppear('UnbindEvent', 'scroll');

Version History

• Version 1.0.7 12 May 2016
  • Test added for GatherElements when action.settings has not yet been defined by @xlshen.
• Version 1.0.6 16 February 2015
  • Added Callback object that can be utilised if needed.
  • Added GatherAfterTrigger property.
  • Now JSLint compliant again
• Version 1.0.5 2 June 2014
  • Add ability for a callback function to be called each time the ShowElements function fires. This can be set using the Callback parameter.
• Version 1.0.4 29 April 2014
  • Add backwards compatibility for older browsers that don’t support window.innerWidth / window.innerHeight and window.pageXOffset / window.pageYOffset
• Version 1.0.3 19 April 2014
  • Update demo URL and fix version number push with 1.0.2
• Version 1.0.2 18 April 2014
  • HideElements function will now fallback to the ElementsToShow parameter if no value is passed into the function.
• Version 1.0.1 18 April 2014
  • BindEvent and UnbindEvent now support the ability for the user to specify the event types. If none is specified it defaults to the initial TriggerType parameter
• Version 1.0.0 18 April 2014
  • Create Manifest file for inclusion in jQuery Plugins site
  • Add MIT license file
  • Minor updates to formatting
  • Added support for some new DOM manipulation event listeners