web-padawan / vanilla-hamburger

Animated hamburger menu icons for modern web apps (1.8 KB) 🍔

vanilla-hamburger is a port of hamburger-react to vanilla Custom Elements.

Features

• Small: Just 1,8 KB (minified and gzipped). 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.
• Simple: Uses native <button> with a click listener internally.
• Accessible: Follows WAI-ARIA guidelines for toggle buttons.
• No dependencies

Live demo

• Website
• Angular example
• LitElement example
• React example
• Svelte example
• Vue example

Installation

npm install vanilla-hamburger --save

Or use one of the following content delivery networks:

unpkg.com CDN:

<script type="module" src="https://unpkg.com/vanilla-hamburger?module"></script>

Skypack CDN:

<script type="module" src="https://cdn.skypack.dev/vanilla-hamburger"></script>

Usage

<tilt-burger size="lg" label="Menu"></tilt-burger>
<script type="module">
  import 'vanilla-hamburger';

  const burger = document.querySelector('tilt-burger');
  burger.addEventListener('pressed-changed', (event) => {
    const pressed = event.detail.value;
  });
</script>

ES modules

vanilla-hamburger is authored using ES modules which are natively supported by modern browsers. However, it also uses "bare module imports" which are not yet standardized and require a small transform.

We recommend the following tools for the ES modules based development:

• @web/dev-server resolves bare module imports on the fly.
• snowpack performs one-time transform when installing dependencies.
• @rollup/plugin-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"	<cross-burger>
"fade-burger.js"	<fade-burger>
"pivot-burger.js"	<pivot-burger>
"rotate-burger.js"	<rotate-burger>
"slant-burger.js"	<slant-burger>
"sling-burger.js"	<sling-burger>
"spin-burger.js"	<spin-burger>
"spiral-burger.js"	<spiral-burger>
"squash-burger.js"	<squash-burger>
"squeeze-burger.js"	<squeeze-burger>
"tilt-burger.js"	<tilt-burger>
"turn-burger.js"	<turn-burger>
"twirl-burger.js"	<twirl-burger>

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 <button> 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 <button>.
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 <squash-burger> and <squeeze-burger>.

Overriding styles

vanilla-hamburger exposes CSS Shadow Parts allowing to override the default styles:

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.

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 <button>, 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 and 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 and Shadow DOM, and does not support IE11 or legacy Edge.

Why vanilla-hamburger?

vanilla-hamburger has all the benefits of hamburger-react 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, it's perfect time to build such tiny and lightweight UI controls as web components rather than framework components.

vanilla-hamburger's Issues

label attribute does not affect aria label

Thanks for this great component!

I've noticed setting the label attribute like this does not appear to set the inner button's aria-label attribute:

    <fade-burger distance="sm" label="Open site menu"></fade-burger>

But setting element.label with javascript does update the aria-label attribute on the button.

It looks like maybe the aria-label is only set in the setter for element.label but maybe this isn't called on init?

The cursor does not become a pointer over the entire element

The cursor does not become a pointer over the whole element, even if the whole element is clickable.

See screencast for illustration:

Kapture.2023-02-27.at.19.17.14.mp4

Consider using native button element internally

Currently, the component sets role="button" on itself, as well as tabindex and then keydown event handler.
This is far from ideal. As an example, Firefox also dispatches clicks on Space, in addition to Enter.

This logic could be simplified a lot by using <button> internally. This would mean the following API changes:

• Adding a label property that would be used to provide an accessible label for the button.
• Adding a button part that would allow to customize button styles.
• Adding a focus() method that would focus the underlying button.
• Using delegatesFocus needs to be evaluated where available (at least in Chrome).

Total size hard coded to 48px

May be I'm missing something, but could it be the that the total size of the icon is hard coded to 48px?

It is possible to set the icons size, but this will "only" reduce the size of the icon and at the same time increase the surrounding margin.

Is there a reason for that? If not, would you accept a pull request to change that?