jQuery ScrollAppear Plugin

Version: 1.0.7
Date Released: 16 October 2012
Last Updated: 12 May 2016

If you have suggestions for features, improvements or spot any bugs, leave a comment at the bottom of the page or alternatively log an issue on GitHub.

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]

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:

TriggerType : "scroll"

A-Z Method List

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
  • 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
  • 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

Subscribe

You'll only get 1 email per month containing new posts (I hate spam as much as you!). You can opt out at anytime.

Categories

Leave a Reply

Your email address will not be published. Required fields are marked *

Preview Comment

18 Comments

  1. Marcel
    http://bit.ly/YdZG1p#comment-282

    Marcel

    It`s a great plugin but it was a little bulky for my needs. I don`t need so may options, so I wrote this:

    function check(){
    	if($(window).scrollTop()+$(window).height()>$(".footer").offset().top){
    		var ideal_number = Math.floor($(window).width()/200);//Number of blocks that fit in a row
    		var add = ideal_number*2;//Add two rows
    		var off = $(".show_this").length%ideal_number;//If the even row got messed up due to page resize
    		if(off){add = ideal_number*2+(ideal_number-off);}
    		var existing = $(".show_this").length;
    		$(".page_item").slice(existing,existing+add).addClass("show_this");
    	}
    }
    $(document).ready(function(){
    	check();
    	setInterval(check,5000);
    });
    
    • Dom Sammut
      http://bit.ly/YdZG1p#comment-283

      Dom Sammut

      Thanks for showing your final solution Marcel!

      • Marcel
        http://bit.ly/YdZG1p#comment-284

        Marcel

        It’s not my final solution, I have edited it quite a bit since this post.

  2. Marcel
    http://bit.ly/YdZG1p#comment-271

    Marcel

    Is is possible to change the amount of items added when the function is triggered?

    • Dom Sammut
      http://bit.ly/YdZG1p#comment-277

      Dom Sammut

      It sure is, you can specify the number of elements to be added with this property: ElementsToShow

      • Marcel
        http://bit.ly/YdZG1p#comment-279

        Marcel

        I completely misread that. I though it was element to show ie, the class name of the element to show when the footer is isible, but, ofcourse, that is something else.

        • Dom Sammut
          http://bit.ly/YdZG1p#comment-280

          Dom Sammut

          Thanks for the feedback, I’ve updated the description in the initial list of properties for the documentation to better describe what that ElementsToShow actually does :)

  3. Marcel
    http://bit.ly/YdZG1p#comment-270

    Marcel

    I am having some trouble implementing this. I set up a simple test page with 100 divs and a footer. I cannot get the plugin to add the classes when the footer is in view.

    • Dom Sammut
      http://bit.ly/YdZG1p#comment-276

      Dom Sammut

      Hey Marcel,

      Have you tried adjusting the PixelOffset? Can you provide an example on jsfiddle.net or somewhere similar?

      Cheers
      Dom

      • Marcel
        http://bit.ly/YdZG1p#comment-278

        Marcel

        Nevermind I figued it out. The scroll never fired because the body was not tall enough to actually scroll. I made the first 3 rows load automatically. I would have replied sooner but earlier, I could not see my comment.

        • Dom Sammut
          http://bit.ly/YdZG1p#comment-281

          Dom Sammut

          Sorry about Marcel, glad you sorted it out :)

  4. Michael Akers
    http://bit.ly/YdZG1p#comment-82

    Michael Akers

    Dom, this is a cool plugin, but I have an issue in the code. I see in the js file the .each section with the list of actions that if found in the page interferes with the plugin operation (passing DomUpdate as the object instead of the ScrollAppear settings). I comment that section out and everything works. Where I am trying to use it I have other page elements being modified with .append or .each and the presence of those methods causes your plugin to not operate. Mainly I’m wondering what that section is meant for?

    • Dom Sammut
      http://bit.ly/YdZG1p#comment-83

      Dom Sammut

      Thanks Michael. The section you’ve mentioned (Line 244 onwards) is there to basically monitor the DOM for any elements that might be added after the plugin has been initialised without having to call jQuery(".myclass").ScrollAppear("DomUpdate");. The demo page demonstrates (the Add Elements button) adding manually created elements on click (after the plugin has been initialised) using the insertBefore jQuery function, which are then picked up by the plugin. I also ran a quick test using .append() and it worked fine. Where have you placed your code in relation to invocation of jQuery ScrollAppear? What version of jQuery are you using? Do you have a link to a page where I can view this issue?

  5. Vladimir Nikolic
    http://bit.ly/YdZG1p#comment-73

    Vladimir Nikolic

    great job! Is it possible to attach a loader gif on scrolling?

    • Dom Sammut
      http://bit.ly/YdZG1p#comment-74

      Dom Sammut

      It sure would be. I have tried to steer clear of implementing that type of functionality in the plugin as I felt that this would be best left to the user to implement based on their requirements. If you have a working example, I’d be happy to give some pointers.

      Would the addition of having the ability to call a function each time a scollappear event is fired be helpful?

      e.g. something like

      $("#test").ScrollAppear({
      CallOnShow : myfunction()
      });

      • Marco
        http://bit.ly/YdZG1p#comment-75

        Marco

        Hello
        I was wondering whether you had a quick example how to use this jquery plugin pulling in wordpress posts – what I’m actually trying to do is to pull in some wordpress galleries – since WP gallery doesn’t support pagination I try to use the offset parameter. hope you got some code to get me going.

        Thank you

        • Dom Sammut
          http://bit.ly/YdZG1p#comment-77

          Dom Sammut

          Hi Marco,

          Unfortunately I don’t have any code for pulling in paginated WordPress galleries, that’s not really within the scope of jQuery ScrollAppear.

          I am looking to push an update to the plugin within the next month to support a callback function as outlined in my previous comment. You could potentially hook an ajax call inside that function, but I don’t have any code examples for this as I don’t use WordPress galleries.

          If you work out how to pull in more galleries into the page and they have the same classes as you’ve used in the initialisation of jQuery ScrollAppear, the plugin will automatically bind to these new elements created (assuming you’ve added them with jQuery) and show them on scroll. The jQuery ScrollAppear demo page has an example of this when you click the “AddElements” button.

          If you have any more questions just let me know or if you’d like link me to some of your work in progress I can provide some pointers.

          Cheers
          Dom

        • Dom Sammut
          http://bit.ly/YdZG1p#comment-95

          Dom Sammut

          Hi Marco,

          Following up from my previous comment, I’ve added a new parameter to the plugin that allows you to pass a callback function each time more elements are displayed. Hopefully this might give you a little help :)

          Cheers
          Dom

css.php