Skip to content

🎉📱Multiplatform lightweight drawer slide-over pane. For modern progressive applications

License

Notifications You must be signed in to change notification settings

dalepo/cupertino-pane

 
 

Repository files navigation

Cupertino Pane

CircleCI npm npm NPM Code Style Code Style

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

  • Small. 5kb (minified and gzipped). No dependencies.
  • Accelerated. 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.

Demonstration

Live Demo Old Version

Cupertino Pane - Roman Antonov Cupertino Pane - Roman Antonov Cupertino Pane - Roman Antonov

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: 20px;
}

Initialize Cupertino Pane

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

jQuery example

$(document).ready(function () {
  //initialize pane when document ready
  var myPane = new CupertinoPane('.cupertino-pane', { /* ... */ });
  myPane.present();
});

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();

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
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 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'cubic-bezier' 'ease' Transition property animation type
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
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
dragByCursor boolean false Drag pane only with draggabale top cursor
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: { // Topper point that pane can reach
      enabled: true, // Enable or disable breakpoint
      height: 0 // Pane breakpoint height
    },
    middle: { ... },
    bottom: { ... }
  }
});

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

Bottom and middle heights normalized accross devices by default

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
onDragEng void: () => {} Executes when drag event complete
onBackdropTap void: () => {} Call when user tap backdrop overlay
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();

moveToBreak('top' | 'middle' | 'bottom')

Will change pane position with animation to selected breakpoint.

myPane.moveToBreak('top');

hide()

Dissappear pane from screen, still keep pane in DOM.

myPane.hide();

destroy({animate: boolean = false})

Remove pane from DOM and clear styles

myPane.destroy();

isHidden()

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');
}

currentBreak()

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

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

disableDrag()

Method disable any drag actions for pane

myPane.disableDrag();

enableDrag()

Method enable any drag actions for pane

myPane.enableDrag();

Attributes

hide-on-bottom

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>

overflow-y

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

  • [UI] Starbucks playground
  • [Docs] All playground live
  • [Docs] Bulletin, Starbucks video
  • [Quality] Click item/drag pane precision on device
  • [Quality] Max diff
  • [Quality] Precision delta counts experiments + option
  • [Quality] Topper than top (if scroll - overflow enable else 10px-20px)
  • [Quality] Auto detection horizontall drag events inside pane
  • [UI] 3D effect (ion-modal example)
  • [UI] Drawer control effect (simple/circle)
  • [UI] 3D button toggle effect
  • [Docs] Docs engine (React)
  • [Docs] Live example hosted in pages
  • [Platforms] React Native version with one core
  • [UI] No taps UI (increase User - Machine information throughput)

Contributing

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

License

Licensed under the MIT License. View license.

About

🎉📱Multiplatform lightweight drawer slide-over pane. For modern progressive applications

Resources

License

Code of conduct

Stars

Watchers

Forks

Packages

No packages published

Languages

  • TypeScript 63.6%
  • HTML 28.1%
  • JavaScript 8.3%