mkPullFresh

Pull to refresh jQuery plugin for mobile and desktop with CSS animation. Extremely simple usage. Asynchronous stop. Fully customizable. Material design included.

Download from GIT Hub Download as NPM package

Basic usage

Include script and style sheet into you page:

<script src="path/to/plugin/mk-pullfresh.min.js" type="text/javascript"></script>
<link  href="path/to/plugin/mk-pullfresh.min.css" rel="stylesheet">

Then initialize mkPullFresh on element you want to pull by one of the ways:

Pull this text down by mouse or finger and drop it to refresh content of the box.

Clickable Clickable element is to show, that all events are workable inside pulled element. It must change color from gray to green. Default swipe is workable too. You can scroll overflowed text with touch devices, mkPullFresh works only from the top of element.

Just overflowed text. Just overflowed text. Just overflowed text. Just overflowed text. Just overflowed text. Just overflowed text. Just overflowed text. Just overflowed text. Just overflowed text.

$('.pulled').mkPullFresh();
$('.pulled').mkPullFresh(function(end){
    // some code, may be async
    end(); // stop pending state of pull indicator
  });
				
$('.pulled').mkPullFresh(options);

Don't forget to call end() from your callback to stop pending state of mkPullFresh

Options

optiondefaultdescription
maxShift100maximum offset in pixels to pull element down
readyShift50offset in pixels to be ready for refresh
pendingShift50offset in pixels in pending state
refresh1500Callback function or milliseconds. Function will be called with only arg - end. End - is a function you have to call to stop pending state of mkPullFresh. 'this' arg will be a mkPullFresh instance.
indicatorHtml''Html code of pull-to-refresh indicator
emitEventsfalse if true, will emit following events on puller:
  • mkPullFreshStart (jqEvent, yShift, plugin),
  • mkPullFreshPull (jqEvent, yShift, plugin)on move,
  • mkPullFreshPending (jqEvent, end, plugin) on refreshing, waiting for the end,
  • mkPullFreshEnd (jqEvent, plugin)
jqEvent - jQuery event, yShift - is a y-axis offset, plugin - is a plugin instance

Understanding dynamics

Apply mkPullFresh to block you want to pull. Attribute data-mkpf-state will be added to it with initial value 'idle'. Also will be prepended div.mk-pullfresh-bubble with initial height 0, with indicator inside. When you pull the block, you increase height of div.mk-pullfresh-bubble, shifting down the content. data-mkpf-state changes its value depending on state: idle>active>ready>pending>idle

mkPullFresh. Pull to refresh plugin scheme

Idle state

Bubble at the top of element is zero height

mkPullFresh. Pull to refresh plugin scheme

Active state

Start to pull, and pump up the bubble

mkPullFresh. Pull to refresh plugin scheme

Ready state

Offset more then readyShift

mkPullFresh. Pull to refresh plugin scheme

Pending state

Puller dropped, plugin is waiting for calling end() callback

Events

If you set option emitEvents to true, then events will be emitted on puller element.

Pull this text down by mouse or finger and drop it to refresh content of the box.

Clickable Clickable element is to show, that all events are workable inside pulled element. It must change color from gray to green. Default swipe is workable too. You can scroll overflowed text with touch devices, mkPullFresh works only from the top of element.

Just overflowed text. Just overflowed text. Just overflowed text. Just overflowed text. Just overflowed text. Just overflowed text. Just overflowed text. Just overflowed text. Just overflowed text.


				
$('#puller').mkPullFresh({ emitEvents: true })
	.on('mkPullFreshStart',  function(e,y,pf)  {mylog('start.');})
	.on('mkPullFreshPull',   function(e,y,pf)  {mylog('start. pull('+y+'). ');})
	.on('mkPullFreshPending',function(e,end,pf){mylog('pending. ',true);setTimeout(end,1000)})
	.on('mkPullFreshEnd',    function(e,pf)  {mylog('end.',true);});
				

eventargumentsdescription
mkPullFreshStartjqEvent, yOffset, pluginwhen pull starts
mkPullFreshPulljqEvent, yOffset, pluginon every pointer (finger) movement
mkPullFreshPendingjqEvent, end, pluginwhen puller dropped, do refresh code here, don't forget to call end()
mkPullFreshEndjqEvent, pluginwhen pull or pending state ends

Plugin instance

Events gets plugin instance as argument. Some of the properties:


propertytypedescription
optionsobjectoptions of current instance
$pullerjQuerypulled element
pullerDOMElelmntpulled element
$containerjQuerypuller parent
$bubblejQuerydiv.mk-pullfresh-bubble with indicator inside
bubbleDOMElelmntdiv.mk-pullfresh-bubble with indicator inside
pointerobject current pointer state:
  • y - current y-position of pointer
  • start - y-position where current pull were started
  • shift - current pointer y-offset

Customizing

You can fully change look and behavior of indicator. Set another html for indicator in options.indicatorHtml. Set context styles depending on attribute data-mkpf-state

Pull this text down by mouse or finger and drop it to refresh content of the box.

Clickable Clickable element is to show, that all events are workable inside pulled element. It must change color from gray to green. Default swipe is workable too. You can scroll overflowed text with touch devices, mkPullFresh works only from the top of element.

Just overflowed text. Just overflowed text. Just overflowed text. Just overflowed text. Just overflowed text. Just overflowed text. Just overflowed text. Just overflowed text. Just overflowed text.

indicatorHtml
<div class="mkpf-envelop">
	<div class="active">pull down</div>
	<div class="ready">drop to refresh</div>
	<div class="pending">pending ...</div>
</div>
javascript
$('#custom1El .puller').mkPullFresh({
	indicatorHtml: '<div class="mkpf-envelop"><div class="active">pull down</div><div class="ready">drop to refresh</div><div class="pending">pending ...</div></div>',
	pendingShift: 35
});
CSS styles
.custom-puller .mkpf-envelop div{
	  display: none;
 }
.custom-puller[data-mkpf-state=active] .active{
  display: block;
}
.custom-puller[data-mkpf-state=ready]  .ready{
 display: block;
}
.custom-puller[data-mkpf-state=pending] .pending{
 display: block;
}
.custom-puller[data-mkpf-state=active]  .mk-pullfresh-bubble{
 background-color: #ddd;
}
.custom-puller[data-mkpf-state=ready]   .mk-pullfresh-bubble{
 background-color: #ffffcc;
}
.custom-puller[data-mkpf-state=pending] .mk-pullfresh-bubble{
 background-color: #ccffcc;
}

Material design style

Another approach is to pull only indicator, but not to pull text, like in mobile Chrome. It's much better for performance, movements looks smoother on mobile devices. It can be done just with CSS. This styles are already included. Just add mkpf-material class to puller.

Pull this text down by mouse or finger and drop it to refresh content of the box.

Clickable Clickable element is to show, that all events are workable inside pulled element. It must change color from gray to green. Default swipe is workable too. You can scroll overflowed text with touch devices, mkPullFresh works only from the top of element.

Just overflowed text. Just overflowed text. Just overflowed text. Just overflowed text. Just overflowed text. Just overflowed text. Just overflowed text. Just overflowed text. Just overflowed text.

.mkpf-material{
	position: relative;
	user-select: none;
}
.mkpf-material .mk-pullfresh-bubble{
	position: absolute;
	width: 100%;
}

.mkpf-material .mkpf-indicator-wrapper{
	background-color: #fff;
	display: inline-block;
	width: 40px;
	height: 40px;
	padding:3px;
	border-radius: 50%;
	border: 1px solid #ddd;
	box-shadow: 2px 0px 10px rgba(0,0,0,.4);
}

Scrolling warning

Don't apply constrains to height with auto scrolls directly to puller. If you want to put scrollable text into constrained blocks like here in examples, wrap it with additional block with constrained height, but don't apply height constrains to the puller.