README

Cupertino Panes

npm npm NPM

Cupertino Panes is multi-functional panes & boards 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.

⭐ We appreciate your star, it helps!

Demonstration
Financial Contributors
Supporting platforms
Getting Started
Settings
Breakpoints
Z-Stack
Callbacks
Public Methods
Attributes
CSS Variables
Keyboard issues
Future Goals
Contributors
Changelog
License

Financial Contributors

Become a financial contributor and help us sustain our community. [Contribute]

Individuals

Organizations

Support this project with your organization. Your logo will show up here with a link to your website. [Contribute]

Demonstration

Supporting platforms

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, bounce: true },
            bottom: { enabled: true, height: 80 },
        },
        onDrag: () => console.log('Drag event')
      }
    );
    myPane.present({animate: true}).then(res => {...});
  };
  </script>
</body>

jQuery example

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

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', settings);
    await myPane.present({animate: true});

Class creation

You can pass html element or string selector to class constructor

// String selector
new CupertinoPane('.cupertino-pane');

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

Settings

Common configuration

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: 700, // Pane breakpoint height
      bounce: true // Bounce pane on transition
    },
    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)

Z-Stack

Configuration for 3D push effects and z-stack

let settings = {
  ...
  zStack: {
    pushElements: ['.card-1', '.main-content'],
    pushYOffset: 10
  }
}

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}): Promise

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

moveToHeight(val: number)

Will move pane to exact height with animation. Breakpoints will saved.

myPane.moveToHeight(575);

hide()

Dissappear pane from screen, still keep pane in DOM.

myPane.hide();

destroy({animate: boolean = false}): Promise

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

backdrop({show: boolean = true})

Show/Hide backdrop method

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

setBreakpoints(breakpoints: PaneBreaks)

Method updates breakpoints configuration for rendered Pane

myPane.setBreakpoints({
  top: {
      enabled: true,
      height: 700,
      bounce: true
  },
  middle: { ... },
  bottom: { ... }
});

preventDismiss(boolean = false)

Use this method to prevent dismiss events. Use onWillDismiss() callback to listen if dismiss event prevented.

const settings = {
  ...
  onWillDismiss: (e) => {
    if (e) {
      console.log(e.prevented);
    }
  }
}

const myPane = new CupertinoPane('.cupertino-pane', settings);
myPane.present({animate: true});
myPane.preventDismiss(true);

calcFitHeight()

Force re-calculate height for fitHeight: true in cases when height was calculated not properly.

myPane.calcFitHeight();

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>

CSS Variables

Keyboard issues

Inputs and textareas in pane may push mobile keyboard on devices, and close pane visibility. Next cases describe how to proper handle this issues.

Browser/WebView

User's must use input focus/blur callback's to handle keyboard. Example:

<input onfocus="keyboardOpen()" onblur="keyboardClose()" />

function keyboardOpen () {
  pane.moveToBreak('top'); // or moveToHeight(current + keyboardHeight);
}
function keyboardClose () {
  pane.moveToBreak('middle'); // or moveToHeight(current - keyboardHeight);
}

Cordova/Phonegap/Capacitor

By default, we are now handle keyboard in hybrid mobile applications and push pane to exact keyboard height. If you would like handle this part by yourself, set option handleKeyboard: false.

Future Goals

Project under regularly maintanance and bug fixes. All new features and new investigations moved to open collective Goals

Contributors

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

Commit Message Format angular commit format

License

Licensed under the MIT License. View license.

Usage no npm install needed!