https://github.com/web-padawan/vanilla-hamburger
Animated hamburger menu icons for modern web apps (1.8 KB) 🍔
https://github.com/web-padawan/vanilla-hamburger
burger custom-elements hamburger hamburger-menu vanilla web-components webcomponents
Last synced: 6 months ago
JSON representation
Animated hamburger menu icons for modern web apps (1.8 KB) 🍔
- Host: GitHub
- URL: https://github.com/web-padawan/vanilla-hamburger
- Owner: web-padawan
- License: mit
- Created: 2020-09-12T12:53:12.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2023-02-09T08:43:16.000Z (over 2 years ago)
- Last Synced: 2025-05-03T02:05:43.211Z (6 months ago)
- Topics: burger, custom-elements, hamburger, hamburger-menu, vanilla, web-components, webcomponents
- Language: TypeScript
- Homepage: https://web-padawan.github.io/vanilla-hamburger/
- Size: 1.1 MB
- Stars: 121
- Watchers: 3
- Forks: 5
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
vanilla-hamburger is a port of hamburger-react to vanilla Custom Elements.
## Features
- **Small**: Just 1,8 KB (minified and gzipped). [Size Limit](https://github.com/ai/size-limit) controls the size.
- **Fast**: Built with standards based Custom Elements.
- **Bulletproof**: Written in strict TypeScript and covered by 30+ tests.
- **Framework-agnostic**: Can be used [with any framework](https://custom-elements-everywhere.com/).
- **Simple**: Uses native `` with a `click` listener internally.
- **Accessible**: Follows [WAI-ARIA](https://www.w3.org/TR/wai-aria-practices/#button) guidelines for toggle buttons.
- **No dependencies**
## Live demo
- [Website](https://web-padawan.github.io/vanilla-hamburger/)
- [Angular example](https://components.studio/edit/B6UIy18tBWekjsdlcIzg)
- [LitElement example](https://components.studio/edit/MwlJAn0K1B5neVtunpFI)
- [React example](https://components.studio/edit/1Cta6NtUgJSSgyOYXB2n)
- [Svelte example](https://components.studio/edit/uL3KYNle783i1ehAlXJa)
- [Vue example](https://components.studio/edit/rsRiCxbap2Gh0wl3JZJn)
## Installation
```
npm install vanilla-hamburger --save
```
Or use one of the following content delivery networks:
[unpkg.com CDN](https://unpkg.com/vanilla-hamburger?module):
```html
```
[Skypack CDN](https://cdn.skypack.dev/vanilla-hamburger):
```html
```
## Usage
```html
import 'vanilla-hamburger';
const burger = document.querySelector('tilt-burger');
burger.addEventListener('pressed-changed', (event) => {
const pressed = event.detail.value;
});
```
## ES modules
**vanilla-hamburger** is authored using ES modules which are [natively supported](https://caniuse.com/es6-module)
by modern browsers. However, it also uses "bare module imports" which are [not yet standardized](https://github.com/WICG/import-maps)
and require a small transform.
We recommend the following tools for the ES modules based development:
- [`@web/dev-server`](https://modern-web.dev/docs/dev-server/overview/) resolves bare module imports on the fly.
- [`snowpack`](https://www.snowpack.dev) performs one-time transform when installing dependencies.
- [`@rollup/plugin-node-resolve`](https://github.com/rollup/plugins/tree/master/packages/node-resolve) is needed when using Rollup.
None of these tools are needed when importing the component from CDN.
## Available variants
**vanilla-hamburger** provides 13 separate elements for different hamburger types.
| File to import | HTML element |
| --------------------- | ------------------ |
| `"cross-burger.js"` | `` |
| `"fade-burger.js"` | `` |
| `"pivot-burger.js"` | `` |
| `"rotate-burger.js"` | `` |
| `"slant-burger.js"` | `` |
| `"sling-burger.js"` | `` |
| `"spin-burger.js"` | `` |
| `"spiral-burger.js"` | `` |
| `"squash-burger.js"` | `` |
| `"squeeze-burger.js"` | `` |
| `"tilt-burger.js"` | `` |
| `"turn-burger.js"` | `` |
| `"twirl-burger.js"` | `` |
When using one hamburger, ~1.8 KB will be added to your bundle (min + gzip).
## Properties
The following properties can be used to customize hamburger elements:
| Property | Default | Description |
| ----------- | -------------------------- | ------------------------------------------------------- |
| `direction` | `left` | The animation direction of the icon, left or right. |
| `disabled` | `false` | When set to true, the internal `` id disabled. |
| `distance` | `md` | The distance between the lines: `sm`, `md` or `lg`. |
| `duration` | `0.4` | The duration of the animation. Can be set to zero. |
| `easing` | `cubic-bezier(0, 0, 0, 1)` | A valid `transition-timing-function` CSS value. |
| `label` | `hamburger` | Accessible label set on the internal ``. |
| `pressed` | `false` | Set to true when element is pressed. |
| `size` | `32` | Size of the icon. Should be a number between 12 and 48. |
**Note**: `direction` property is not supported by `` and ``.
## Overriding styles
**vanilla-hamburger** exposes [CSS Shadow Parts](https://developer.mozilla.org/en-US/docs/Web/CSS/::part)
allowing to override the default styles:
```css
cross-burger {
color: #999;
}
cross-burger[pressed] {
color: #666;
}
cross-burger[disabled] {
opacity: 0.7;
}
cross-burger::part(bar) {
border-radius: 9em;
}
cross-burger::part(button) {
outline: none;
background: currentColor;
border-radius: 50%;
opacity: 0;
transition: opacity 0.5s;
}
cross-burger::part(button):hover {
opacity: 0.12;
}
cross-burger::part(button):focus {
opacity: 0.16;
}
```
## Base classes
**vanilla-hamburger** provides a set of base classes that can be imported without registering custom
elements. This is useful if you want to create your own hamburger icon with a different tag name.
```js
import { Cross } from 'vanilla-hamburger/lib/entrypoints/cross.js';
customElements.define('custom-burger', class extends Cross {});
```
## Accessibility
It is recommended to have a tap/click area of at least 48x48 pixels. Therefore, padding will be
added around the icon to create a surface of exactly this size.
Keyboard interaction is provided using native ``, which dispatches the `click` event on
Enter and Space keys. The underlying native button has `aria-pressed` attribute
set based on the `pressed` property.
Remember to use `label` property to provide an accessible label for the native button.
## TypeScript support
**vanilla-hamburger** supports TypeScript and ships with types in the library itself; no need for any other install.
All the included custom elements are compatible with [lit-analyzer](https://www.npmjs.com/package/lit-analyzer) and
[lit-plugin](https://marketplace.visualstudio.com/items?itemName=runem.lit-plugin) extension for Visual
Studio Code, so you can benefit from type checking in lit-html templates.
## Browser support
**vanilla-hamburger** uses [Custom Elements](https://caniuse.com/#feat=custom-elementsv1) and [Shadow DOM](https://caniuse.com/#feat=shadowdomv1),
and does not support IE11 or legacy Edge.
## Why vanilla-hamburger?
**vanilla-hamburger** has all the benefits of [hamburger-react](https://github.com/luukdv/hamburger-react#yet-another-hamburger-library) with one important difference.
While `hamburger-react` does not have direct dependencies, it still expects you to use React. This
means that Angular, Vue, Svelte or vanilla JS users would have an **extra** dependency in their apps.
Now when all the evergreen browsers support standards based [Custom Elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements),
it's perfect time to build such tiny and lightweight UI controls as web components rather than framework components.