Cupertino Pane

Cupertino Pane is great modern slide-over pane with touch technologies.



Small. 5kb (minified and gzipped). No dependencies.

5kb (minified and gzipped). No dependencies. Accelerated. Hardware accelerated transitions and amazing native behavior.

Hardware accelerated transitions and amazing native behavior. Progressive. Useful for mobile/web/hybrid applications.

Right like in Apple Maps, Apple Stocks, Apple Music and other modern apps.

⭐ We appreciate your star, it helps!

Demonstration

Supporting platforms

We officially support the last two versions of every major browser. Specifically, we test on the following browsers

Browser Operating system Chrome Android, Windows, macOS, and Linux Firefox Windows, macOS, and Linux Safari iOS WkWebView iOS Android WebView Android

Getting Started

Install via NPM

npm install cupertino-pane

Use from CDN

If you don't want to include Cupertino Pane files in your project, you may use it from CDN. The following files are available:

< script src = " https://unpkg.com/cupertino-pane/dist/cupertino-pane.js " > < / script > < script src = " https://unpkg.com/cupertino-pane/dist/cupertino-pane.min.js " > < / script >

Include Files To App/Website

<! DOCTYPE html > < html lang = " en " > < body > ... < script src = " path/to/cupertino-pane.min.js " > </ script > </ body > </ html >

Add HTML Layout

< div class = " cupertino-pane " > < h1 > Header </ h1 > < div class = " content " > Content </ div > </ div >

Additional CSS Styles

. cupertino-pane { margin : 20 px ; }

Initialize Cupertino Pane

< body > ... < script > window . onload = function ( ) { var myPane = new CupertinoPane ( ' .cupertino-pane ' , { parentElement : ' body ' , breaks : { middle : { enabled : true , height : 300 , bounce : true } , bottom : { enabled : true , height : 80 } , } , onDrag : ( ) => console . log ( ' Drag event ' ) } ) ; myPane . present ( { animate : true } ) ; } ; </ script > </ body >

jQuery example

$ ( document ) . ready ( function ( ) { var myPane = new CupertinoPane ( ' .cupertino-pane ' , { } ) ; myPane . present ( { animate : true } ) ; } ) ;

As an ES module

Cupertino Pane package comes with ES module version which can be used where supported or with bundlers like Webpack or Rollup:

import { CupertinoPane , CupertinoSettings } from ' cupertino-pane ' ; let settings : CupertinoSettings = { } ; let myPane = new CupertinoPane ( ' .cupertino-pane ' , CupertinoSettings ) ; myPane . present ( { animate : true } ) ;

Class creation

You can pass html element or string selector to class constructor

new CupertinoPane ( ' .cupertino-pane ' ) ; let element = document . querySelector ( ' .cupertino-pane ' ) ; new CupertinoPane ( element ) ;

Settings

Common configuration

Property Type Default Description parentElement string Parent element selector Element selector where pane will rendered followerElement string Follower element selector Element with selector will following pane transitions pushElement string Push element selector DOM Element will be pushed and scaled pushMinHeight number Most bottom available point Height from which 3d push effect will be started initialBreak 'top' \| 'middle' \| 'bottom' 'middle' Initial pane position darkMode boolean false Initial pane styles backdrop boolean false Dimmed overlay will rendered with pane if true backdropOpacity number 0.4 Dimmed overlay opacity value animationType string 'ease' Base transition timing function animationDuration number 300 Transition property duration bottomClose boolean false Close pane with drag to bottom breakpoint freeMode boolean false On true will remove automatical magnetic effects to near breakpoint lowerThanBottom boolean true By default allow user to drag pane lower than bottom position. On false will automatically place pane to bottom position on lower than bottom attemption upperThanTop boolean false Allow user to drag pane upper than maximum top position. Useful with bulletin style without overflow-y touchAngle number null Allowable angle (in degrees) to trigger touch move buttonClose boolean true Determinate whetever close button will render or not bottomOffset number 0 Margin bottom for pane from screen bottom point topperOverflow boolean true Ability to scroll content inside pane if topper point reached topperOverflowOffset number 0 Offset from screen bottom to the end of overflow content showDraggable boolean true Render rectangular shape on the top of pane draggableOver boolean true Render rectangular shape over a pane clickBottomOpen boolean true If bottom position reached, simple click to pane will open pane to the next upper point dragBy string[] null Array of selectors for whom elements drag events will be attached. By default drag events attached to pane element. If you are about to drag only with draggable component set option to ['.pane .draggable'] preventClicks boolean true Prevent accidental unwanted clicks events during move gestures touchMoveStopPropagation boolean false If enabled, then propagation of "touchmove" will be stopped simulateTouch boolean true Simulate touch events for Desktop passiveListeners boolean true (Indicates that the function specified by listener will never call preventDefault())

Breakpoints

Package now supports 3 base breakpoints

const pane = new CupertinoPane ( ' .cupertino-pane ' , { breaks : { top : { enabled : true , height : 700 , bounce : true } , middle : { ... } , bottom : { ... } } } ) ;

Bottom and middle heights normalized accross devices by default

Default top height: window.screen.height - (135 * 0.35)

Add property bounce to break and enjoy transitions in apple stocks style with cubic-bezier(0.175, 0.885, 0.370, 1.120)

Callbacks

The function that executes when the event fires.

Name Type Description onDidDismiss void: () => {} Call after pane will dissapeared onWillDismiss void: () => {} Call before pane will dissapeared onDidPresent void: () => {} Call after pane will present onWillPresent void: () => {} Call before panel will present onDragStart void: () => {} Call when detect user drag event on pane onDrag void: () => {} Call executes on each new position of pane onDragEnd void: () => {} Executes when drag event complete onBackdropTap void: () => {} Call when user tap backdrop overlay onTransitionStart void: () => {} Executes before auto transition and animation start onTransitionEnd void: () => {} Executes when transition and animation complete

Public Methods

present({animate: boolean = false})

Will render pane DOM and show pane with setted params.

myPane . present ( ) ;

Will change pane position with animation to selected breakpoint.

myPane . moveToBreak ( ' top ' ) ;

Dissappear pane from screen, still keep pane in DOM.

myPane . hide ( ) ;

destroy({animate: boolean = false})

Remove pane from DOM and clear styles

myPane . destroy ( ) ;

Determinate if pane position was moved out of screen, but pane still exist in DOM. true - in DOM but not visible, false - in DOM and visible, null - not rendered

if ( myPane . isHidden ( ) ) { myPane . moveToBreak ( ' top ' ) ; }

Method return current break position in text format ('top' | 'middle' | 'bottom)

if ( myPane . currentBreak ( ) === ' top ' ) { myPane . moveToBreak ( ' bottom ' ) ; }

Method disable any drag actions for pane

myPane . disableDrag ( ) ;

Method enable any drag actions for pane

myPane . enableDrag ( ) ;

backdrop({show: boolean = true})

Show/Hide backdrop method

myPane . backdrop ( { show : true } ) ; myPane . backdrop ( { show : false } ) ;

Attributes

Set for element to automaticaly hide on reach bottom breakpoint.

< div class = " cupertino-pane " > < h1 > Header </ h1 > < div class = " content " hide-on-bottom > Content </ div > </ div >

Set for element with overflow ability. By default using for full pane area, but in some cases good useful with header.

< div class = " cupertino-pane " > < h1 > Header </ h1 > < div class = " content " overflow-y > Content </ div > </ div >

Future Goals

[Feature] Top-to-bottom direction

[Feature] Horizontal directions

[Showcase] Apple Music F7

[Docs] Package branding

[Docs] Docs engine (F7)

[Accurance] Draw experiment application (Normal/TimeStamp/Native) - Native Touch Plugin

[Platforms] React Native version

[Platforms] C++ QT version

Contributing

We are welcome contributions of all kinds from anyone. Please review the contributing guideline.

License

Licensed under the MIT License. View license.