Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/mango/slideout

A touch slideout navigation menu for your mobile web apps.
https://github.com/mango/slideout
menu-navigation offcanvas sidebar slideout-menu touch-events
Last synced: 5 days ago
JSON representation
A touch slideout navigation menu for your mobile web apps.
Host: GitHub
URL: https://github.com/mango/slideout
Owner: Mango
License: mit
Created: 2015-02-02T01:05:43.000Z (almost 10 years ago)
Default Branch: master
Last Pushed: 2020-09-20T04:51:22.000Z (over 4 years ago)
Last Synced: 2024-12-17T08:05:12.918Z (5 days ago)
Topics: menu-navigation, offcanvas, sidebar, slideout-menu, touch-events
Language: JavaScript
Homepage: https://slideout.js.org
Size: 5.7 MB
Stars: 7,935
Watchers: 223
Forks: 1,150
Open Issues: 72
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project

awesome-javascript - slideout - A touch slideout navigation menu for your mobile web apps. - ★ 7513 (Menu)
awesome-frontend-libraries - slideout
README

        # Slideout.js

[![NPM version][npm-image]][npm-link] [![License][lic-image]][npm-link] [![Build status][travis-image]][travis-link] [![Coverage Status][coverage-image]][coverage-link] [![Dependency status][deps-image]][deps-link] [![devDependency status][devdeps-image]][devdeps-link] [![downloads][dt-image]][npm-link]

> A touch slideout navigation menu for your mobile web apps.

## Features

- Dependency-free.

- Simple markup.

- Native scrolling.

- Easy customization.

- CSS transforms & transitions.

- Just 2 Kb! (min & gzip)

## Demo

[Check out the demo](https://mango.github.io/slideout/) to see it in action (on your mobile or emulate touches on your browser).



## Installation

Slideout is available on cdnjs

```html

```

Also you can use one of many package managers

    $ npm install slideout

    $ spm install slideout

    $ bower install slideout.js

    $ component install mango/slideout

## Usage

Implementing Slideout.js into your project is easy.

First of all, you'll need to create your markup. You should have a menu (`#menu`) and a main content (`#panel`) into your body.

```html

  

    
Menu

  

  

    
Panel

  

```

Add the Slideout.js styles (index.css) in your web application.

```css

body {

  width: 100%;

  height: 100%;

}

.slideout-menu {

  position: fixed;

  top: 0;

  bottom: 0;

  width: 256px;

  min-height: 100vh;

  overflow-y: scroll;

  -webkit-overflow-scrolling: touch;

  z-index: 0;

  display: none;

}

.slideout-menu-left {

  left: 0;

}

.slideout-menu-right {

  right: 0;

}

.slideout-panel {

  position: relative;

  z-index: 1;

  will-change: transform;

  background-color: #FFF; /* A background-color is required */

  min-height: 100vh;

}

.slideout-open,

.slideout-open body,

.slideout-open .slideout-panel {

  overflow: hidden;

}

.slideout-open .slideout-menu {

  display: block;

}

```

Then you just include Slideout.js, create a new instance with some options and call the toggle method:

```html

  var slideout = new Slideout({

    'panel': document.getElementById('panel'),

    'menu': document.getElementById('menu'),

    'padding': 256,

    'tolerance': 70

  });

  // Toggle button

  document.querySelector('.toggle-button').addEventListener('click', function() {

    slideout.toggle();

  });

```

#### Full example

```html

  

    

    Slideout Demo

    

    

    

    

    

    

      body {

        width: 100%;

        height: 100%;

      }

      .slideout-menu {

        position: fixed;

        left: 0;

        top: 0;

        bottom: 0;

        right: 0;

        z-index: 0;

        width: 256px;

        overflow-y: scroll;

        -webkit-overflow-scrolling: touch;

        display: none;

      }

      .slideout-panel {

        position: relative;

        z-index: 1;

        will-change: transform;

      }

      .slideout-open,

      .slideout-open body,

      .slideout-open .slideout-panel {

        overflow: hidden;

      }

      .slideout-open .slideout-menu {

        display: block;

      }

    

  

  

    

      
Menu

    

    

      

        ☰

        
Panel

      

    

    

    

      var slideout = new Slideout({

        'panel': document.getElementById('panel'),

        'menu': document.getElementById('menu'),

        'padding': 256,

        'tolerance': 70

      });

      // Toggle button

      document.querySelector('.toggle-button').addEventListener('click', function() {

        slideout.toggle();

      });

    

  

```

## Browser Support

- Chrome (IOS, Android, desktop)

- Firefox (Android, desktop)

- Safari (IOS, Android, desktop)

- Opera (desktop)

- IE 10+ (desktop and mobile)

## API

### Slideout(options)

Create a new instance of `Slideout`.

- `options` (Object) - Options to customize a new instance of Slideout.

- `options.panel` (HTMLElement) - The DOM element that contains all your application content (`.slideout-panel`).

- `options.menu` (HTMLElement) - The DOM element that contains your menu application (`.slideout-menu`).

- `[options.duration]` (Number) - The time (milliseconds) to open/close the slideout. Default: `300`.

- `[options.easing]` (String) - The CSS effect to use when animating the opening and closing of the slideout. Default: `ease`. Possible values:

    - `ease`

    - `linear`

    - `ease-in`

    - `ease-out`

    - `ease-in-out`

    - `step-start`

    - `step-end`

    - [`cubic-bezier`](http://cubic-bezier.com/)

- `[options.padding]` (Number) - Default: `256`.

- `[options.tolerance]` (Number) - The number of `px` needed for the menu can be opened completely, otherwise it closes. Default: `70`.

- `[options.touch]` (Boolean) - Set this option to false to disable Slideout touch events. Default: `true`.

- `[options.side]` (String) - The side to open the slideout (`left` or `right`). Default: `left`.

```js

var slideout = new Slideout({

  'panel': document.getElementById('main'),

  'menu': document.getElementById('menu'),

  'padding': 256,

  'tolerance': 70,

  'easing': 'cubic-bezier(.32,2,.55,.27)'

});

```

### Slideout.open();

Opens the slideout menu. It emits `beforeopen` and `open` events.

```js

slideout.open();

```

### Slideout.close();

Closes the slideout menu. It emits `beforeclose` and `close` events.

```js

slideout.close();

```

### Slideout.toggle();

Toggles (open/close) the slideout menu.

```js

slideout.toggle();

```

### Slideout.isOpen();

Returns `true` if the slideout is currently open, and `false` if it is closed.

```js

slideout.isOpen(); // true or false

```

### Slideout.destroy();

Cleans up the instance so another slideout can be created on the same area.

```js

slideout.destroy();

```

### Slideout.enableTouch();

Enables opening the slideout via touch events.

```js

slideout.enableTouch();

```

### Slideout.disableTouch();

Disables opening the slideout via touch events.

```js

slideout.disableTouch();

```

### Slideout.on(event, listener);

```js

slideout.on('open', function() { ... });

```

### Slideout.once(event, listener);

```js

slideout.once('open', function() { ... });

```

### Slideout.off(event, listener);

```js

slideout.off('open', listener);

```

### Slideout.emit(event, ...data);

```js

slideout.emit('open');

```

## Events

An instance of Slideout emits the following events:

- `beforeclose`

- `close`

- `beforeopen`

- `open`

- `translatestart`

- `translate`

- `translateend`

The slideout emits `translatestart`, `translate` and `translateend` events only when it is opening/closing via touch events.

```js

slideout.on('translatestart', function() {

  console.log('Start');

});

slideout.on('translate', function(translated) {

  console.log('Translate: ' + translated); // 120 in px

});

slideout.on('translateend', function() {

  console.log('End');

});

// 'Start'

// 'Translate 120'

// 'End'

```

## `data-slideout-ignore` attribute

You can use the special HTML attribute `data-slideout-ignore` to disable dragging on some elements. For example, if you have to prevent `slideout` will open when touch on carousels, maps, iframes, etc.

```html

  

    
Panel

  

  

    Carousel

    ...

  


```

## npm-scripts

```

$ npm run build

```

```

$ npm run dist

```

```

$ npm test

```

```

$ npm run hint

```

## FAQ

### How to add a toggle button.

```js

// vanilla js

document.querySelector('.toggle-button').addEventListener('click', function() {

  slideout.toggle();

});

// jQuery

$('.toggle-button').on('click', function() {

    slideout.toggle();

});

```

### How to open slideout from right side.

You should use the `side` option with the value `right`.

```js

var slideout = new Slideout({

  'panel': document.getElementById('content'),

  'menu': document.getElementById('menu'),

  'side': 'right'

});

```

### How to enable slideout only on mobile devices.

You should use `mediaqueries`:

```css

@media screen and (min-width: 780px) {

  .slideout-panel {

    margin-left: 256px;

  }

  .slideout-menu {

    display: block;

  }

  .btn-hamburger {

    display: none;

  }

}

```

Demo: http://codepen.io/pazguille/pen/mEdQvX

### How to use slideout with a fixed header.

First, you should define the styles for your fixed header:

```css

.fixed-header {

  position: fixed;

  width: 100%;

  height: 50px;

  backface-visibility: hidden;

  z-index: 2;

  background-color: red;

}

```

Then, using slideout's events you should translate the fixed header:

```js

var fixed = document.querySelector('.fixed-header');

slideout.on('translate', function(translated) {

  fixed.style.transform = 'translateX(' + translated + 'px)';

});

slideout.on('beforeopen', function () {

  fixed.style.transition = 'transform 300ms ease';

  fixed.style.transform = 'translateX(256px)';

});

slideout.on('beforeclose', function () {

  fixed.style.transition = 'transform 300ms ease';

  fixed.style.transform = 'translateX(0px)';

});

slideout.on('open', function () {

  fixed.style.transition = '';

});

slideout.on('close', function () {

  fixed.style.transition = '';

});

```

Demo: http://codepen.io/pazguille/pen/ZBxdgw

### How to disable dragging on some elements.

You can use the attribute `data-slideout-ignore` to disable dragging on some elements:

```html

  

    
Menu

  

  

    
Panel

  

  

    Carousel

    ...

  


```

### How to add an overlay to close the menu on click.

You can do that using the powerful `slideout` API and a little extra CSS:

```css

.panel:before {

  content: '';

  display: block;

  background-color: rgba(0,0,0,0);

  transition: background-color 0.5s ease-in-out;

}

.panel-open:before {

  position: absolute;

  top: 0;

  bottom: 0;

  width: 100%;

  background-color: rgba(0,0,0,.5);

  z-index: 99;

}

```

```js

function close(eve) {

  eve.preventDefault();

  slideout.close();

}

slideout

  .on('beforeopen', function() {

    this.panel.classList.add('panel-open');

  })

  .on('open', function() {

    this.panel.addEventListener('click', close);

  })

  .on('beforeclose', function() {

    this.panel.classList.remove('panel-open');

    this.panel.removeEventListener('click', close);

  });

```

Demo: http://codepen.io/pazguille/pen/BQYRYK

## With :heart: by

- Guille Paz (Front-end developer | Web standards lover)

- E-mail: [[email protected]](mailto:[email protected])

- Twitter: [@pazguille](http://twitter.com/pazguille)

- Web: [http://pazguille.me](http://pazguille.me)

## License

MIT license. Copyright © 2015 [Mango](http://getmango.com).

[npm-image]: https://img.shields.io/npm/v/slideout.svg

[lic-image]: https://img.shields.io/npm/l/slideout.svg

[npm-link]: https://npmjs.org/package/slideout

[travis-image]: https://img.shields.io/travis/Mango/slideout.svg

[travis-link]: https://travis-ci.org/Mango/slideout

[deps-image]: https://img.shields.io/david/mango/slideout.svg

[deps-link]: https://david-dm.org/mango/slideout

[devdeps-image]: https://img.shields.io/david/dev/mango/slideout.svg

[devdeps-link]: https://david-dm.org/mango/slideout#info=devDependencies

[dt-image]: https://img.shields.io/npm/dt/slideout.svg

[coverage-image]: https://img.shields.io/coveralls/Mango/slideout.svg

[coverage-link]: https://coveralls.io/github/Mango/slideout