.scrollTo()

.scrollTo( target, options, [, complete] ) Returns: jQuery

Description: Scroll page or scrollable element to a specific offset or target element.

  • version pending: 1.9.x.scrollTo( target, options, [, complete] )

    targetA selector, element, or number.

    optionsA map of additional options to pass to the method. Supported keys:

    • scrollTarget: A element, string, or number which indicates desired scroll position.
    • offsetTop: A number that defines additional spacing above scroll target.
    • duration: A string or number determining how long the animation will run.
    • easing: A string indicating which easing function to use for the transition.

    completeA function to call once the animation is complete.

The .scrollTo() method animates page or element scrolling to a specified target. The specified target can be an integer, an element, or a variable referencing an element. The only required parameter is the target.

ScrollTo Properties and Values

Any numeric property values should be a single numeric value. The target and scrollTarget properties are the same with scrollTarget taking precedence over target. When passing a numeric value into either target or scrollTarget it must be an integer and not a string.

Durations are given in milliseconds; higher values indicate slower scrolling animation, not faster. The default duration is 500 milliseconds. The strings 'fast' and 'slow' can be supplied to indicate durations of 200 and 600 milliseconds, respectively.

Complete Function

If supplied, the complete callback function is fired once scrolling is complete. This can be useful for stringing different animations together in sequence. The callback is not sent any arguments, but this is set to the DOM element being animated. If multiple elements are animated, the callback is executed once per matched element, not once for the scroll animation as a whole.

Basic Usage

To scroll the screen to a matched target element:

$('body').scrollTo('#target');

To scroll a particular scrollable element to a specified value:

$('#content').scrollTo(500);

Scrolling to a desired element with options set:

$('body').scrollTo('#post-5',{duration:'slow', offsetTop : '50'});

Plugin Source:


$
.fn.scrollTo = function( target, options, callback ){
 
if(typeof options == 'function' && arguments.length == 2){ callback = options; options = target; }
 
var settings = $.extend({
    scrollTarget  
: target,
    offsetTop    
: 50,
    duration      
: 500,
    easing        
: 'swing'
 
}, options);
 
return this.each(function(){
   
var scrollPane = $(this);
   
var scrollTarget = (typeof settings.scrollTarget == "number") ? settings.scrollTarget : $(settings.scrollTarget);
   
var scrollY = (typeof scrollTarget == "number") ? scrollTarget : scrollTarget.offset().top + scrollPane.scrollTop() - parseInt(settings.offsetTop);
    scrollPane
.animate({scrollTop : scrollY }, parseInt(settings.duration), settings.easing, function(){
     
if (typeof callback == 'function') { callback.call(this); }
   
});
 
});
}

Note: Currently the core jQuery library includes "<code>linear</code>" and "<code>swing</code>". To use other easing methods you will need to extend your easing methods via separate plugin.

Examples:

Example: Click the button to animate the div with a number of different properties.

<!DOCTYPE html>
<html>
<head>
	<style>
		#demo1 { position:relative; height:350px; }
		#demo-nav { position:absolute; top:5px; margin:5px; }
		#demo-stage { position:relative; display:block; top:40px; background:#fff; height:300px; overflow:auto; }
		#demo-stage li, #demo-stage li h3 { color:#777; }
		#demo-stage li.active, #demo-stage li.active h3 { color:#000; }
	</style>
	<script src="http://code.jquery.com/jquery-latest.js"></script>
	<script src="jquery-scrollTo.js"></script>
</head>
<body>

<div id="demo1">
	<section id="demo-nav">
		<nav>
			<span>Scroll To: </span>
			<button class="next">Next Chapter</button>
			<button class="last">Last Chapter</button>
			<button class="first">First Chapter</button>
		</nav>
	</section>
	<section id="demo-stage" class="jq-clearfix">
		<ul>
			<li><h3>Chapter {nth-child}</h3> <p>{content}</p></li>
		</ul>
		<div class="jq-clearfix"></div>
	</section>
</div>

<script>
// [start] Demo Code //
	var $chapters = $('#demo-stage').find('ul').children('li');
	var $chScrollPositions = new Array();
	
	// Cache Scroll Positions for Each Chapter
	$chapters.each(function(i){
		$chScrollPositions[i] = Math.round($(this).offset().top - $('#demo-stage').offset().top) - 10;
	});
	$chapters.eq(0).addClass('active'); // Set First Chapter Active on Start
	
	$('#demo-nav > nav > button').click(function(){
		var last = $chapters.parent().find('li.active').removeClass('active').index();
		var next;
		
		switch($(this).index()){
			case 1:	// Action - Next Chapter
				next = (last + 1 == $chapters.length) ? 0 : last + 1; // Loop around to first chapter
			break;
			case 2:	// Action - Last Chapter
				next = $chapters.length - 1;
			break;
			case 3:	// Action - First Chapter
				next = 0;
			break;
		}
		$chapters.eq(next).addClass('active'); // Set Next Chapter Active
		$('#demo-stage').scrollTo($chScrollPositions[next]);
	});
// [end] Demo Code //
</script>

</body>
</html>

Demo:

  • Chapter 1

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam ut lorem ipsum. Aenean ut mauris dolor, quis interdum neque. Maecenas consectetur lorem et mi viverra viverra. Etiam vel lorem sagittis quam consequat convallis. Ut pellentesque neque eu sem vulputate nec vestibulum nisi lobortis.

  • Chapter 2

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam ut lorem ipsum. Aenean ut mauris dolor, quis interdum neque. Maecenas consectetur lorem et mi viverra viverra. Etiam vel lorem sagittis quam consequat convallis. Ut pellentesque neque eu sem vulputate nec vestibulum nisi lobortis.

  • Chapter 3

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam ut lorem ipsum. Aenean ut mauris dolor, quis interdum neque. Maecenas consectetur lorem et mi viverra viverra. Etiam vel lorem sagittis quam consequat convallis. Ut pellentesque neque eu sem vulputate nec vestibulum nisi lobortis.

  • Chapter 4

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam ut lorem ipsum. Aenean ut mauris dolor, quis interdum neque. Maecenas consectetur lorem et mi viverra viverra. Etiam vel lorem sagittis quam consequat convallis. Ut pellentesque neque eu sem vulputate nec vestibulum nisi lobortis.

  • Chapter 5

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam ut lorem ipsum. Aenean ut mauris dolor, quis interdum neque. Maecenas consectetur lorem et mi viverra viverra. Etiam vel lorem sagittis quam consequat convallis. Ut pellentesque neque eu sem vulputate nec vestibulum nisi lobortis.

  • Chapter 6

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam ut lorem ipsum. Aenean ut mauris dolor, quis interdum neque. Maecenas consectetur lorem et mi viverra viverra. Etiam vel lorem sagittis quam consequat convallis. Ut pellentesque neque eu sem vulputate nec vestibulum nisi lobortis.

  • Chapter 7

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam ut lorem ipsum. Aenean ut mauris dolor, quis interdum neque. Maecenas consectetur lorem et mi viverra viverra. Etiam vel lorem sagittis quam consequat convallis. Ut pellentesque neque eu sem vulputate nec vestibulum nisi lobortis.

  • Chapter 8

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam ut lorem ipsum. Aenean ut mauris dolor, quis interdum neque. Maecenas consectetur lorem et mi viverra viverra. Etiam vel lorem sagittis quam consequat convallis. Ut pellentesque neque eu sem vulputate nec vestibulum nisi lobortis.

  • Chapter 9

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam ut lorem ipsum. Aenean ut mauris dolor, quis interdum neque. Maecenas consectetur lorem et mi viverra viverra. Etiam vel lorem sagittis quam consequat convallis. Ut pellentesque neque eu sem vulputate nec vestibulum nisi lobortis.

  • Chapter 10

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam ut lorem ipsum. Aenean ut mauris dolor, quis interdum neque. Maecenas consectetur lorem et mi viverra viverra. Etiam vel lorem sagittis quam consequat convallis. Ut pellentesque neque eu sem vulputate nec vestibulum nisi lobortis.