or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-hamburger-react

Animated hamburger menu icons for React with CSS-driven transitions and comprehensive accessibility features

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/hamburger-react@2.5.x

To install, run

npx @tessl/cli install tessl/npm-hamburger-react@2.5.0

index.mddocs/

Hamburger React

Hamburger React is a React library providing 14 different animated hamburger menu icons with CSS-driven transitions. Built with TypeScript and zero runtime dependencies, it offers elegant animations optimized for performance using pure CSS transforms without JavaScript animations.

Package Information

  • Package Name: hamburger-react
  • Package Type: npm
  • Language: TypeScript
  • Installation:
    npm install hamburger-react

Core Imports

import Hamburger from "hamburger-react";

For specific animations:

import { Cross, Spin, Fade, Tilt, Rotate } from "hamburger-react";

For CommonJS:

const Hamburger = require("hamburger-react").default;
const { Cross, Spin, Fade } = require("hamburger-react");

Basic Usage

import React, { useState } from "react";
import Hamburger from "hamburger-react";

function App() {
  const [isOpen, setOpen] = useState(false);
  
  return (
    <Hamburger toggled={isOpen} toggle={setOpen} />
  );
}

Callback-based usage:

import Hamburger from "hamburger-react";

function App() {
  return (
    <Hamburger onToggle={toggled => console.log('Hamburger is', toggled ? 'open' : 'closed')} />
  );
}

Architecture

Hamburger React is built around several key components:

  • Base Burger Component: Internal component handling shared logic, calculations, and state management
  • Animation Variants: 16 specialized components implementing different visual effects using the render prop pattern
  • Common Props Interface: Unified API (
    CommonBurgerProps
    ) shared across all animation variants
  • CSS-Driven Animations: Performance-optimized using CSS transforms and transitions, avoiding expensive JavaScript animations
  • Accessibility: Full keyboard support, ARIA attributes, and recommended 48x48 pixel touch areas

Capabilities

Default Hamburger Animation

The default export provides the Tilt animation - tilts 90 degrees and transforms lines into an X shape.

/**
 * Default hamburger component with Tilt animation
 */
declare const Hamburger: React.FunctionComponent<CommonBurgerProps>;

export default Hamburger;

Animation Variants

All animation components share the same props interface but provide different visual effects.

/**
 * Cross animation - Simple X formation using 2 lines
 */
export const Cross: React.FunctionComponent<CommonBurgerProps>;

/**
 * Divide animation - Lines divide and separate
 */
export const Divide: React.FunctionComponent<CommonBurgerProps>;

/**
 * Fade animation - Lines fade in/out transition
 */
export const Fade: React.FunctionComponent<CommonBurgerProps>;

/**
 * Pivot animation - Lines pivot around center point
 */
export const Pivot: React.FunctionComponent<CommonBurgerProps>;

/**
 * Rotate animation - Entire burger rotates transformation
 */
export const Rotate: React.FunctionComponent<CommonBurgerProps>;

/**
 * Slant animation - Lines slant into formation
 */
export const Slant: React.FunctionComponent<CommonBurgerProps>;

/**
 * Sling animation - Lines sling/swing motion
 */
export const Sling: React.FunctionComponent<CommonBurgerProps>;

/**
 * Spin animation - Spinning rotation animation
 */
export const Spin: React.FunctionComponent<CommonBurgerProps>;

/**
 * Spiral animation - Spiral motion transformation
 */
export const Spiral: React.FunctionComponent<CommonBurgerProps>;

/**
 * Squash animation - Squashing/compressing effect
 */
export const Squash: React.FunctionComponent<CommonBurgerProps>;

/**
 * Squeeze animation - Squeezing motion
 */
export const Squeeze: React.FunctionComponent<CommonBurgerProps>;

/**
 * Tilt animation - Tilts 90 degrees with lines forming X
 */
export const Tilt: React.FunctionComponent<CommonBurgerProps>;

/**
 * Turn animation - Turning motion animation
 */
export const Turn: React.FunctionComponent<CommonBurgerProps>;

/**
 * Twirl animation - Twirling motion effect
 */
export const Twirl: React.FunctionComponent<CommonBurgerProps>;

Usage Examples:

import { Cross, Spin, Fade } from "hamburger-react";
import { useState } from "react";

function NavigationMenu() {
  const [isOpen, setOpen] = useState(false);
  
  return (
    <div>
      {/* Different animation styles */}
      <Cross toggled={isOpen} toggle={setOpen} />
      <Spin toggled={isOpen} toggle={setOpen} color="#ff6b6b" />
      <Fade 
        toggled={isOpen} 
        toggle={setOpen}
        size={40}
        duration={0.6}
        rounded
      />
    </div>
  );
}

Component Configuration

All hamburger components accept comprehensive configuration options for appearance and behavior.

import { Dispatch, SetStateAction } from 'react';

export interface CommonBurgerProps {
  /** The color of the icon bars, accepts any CSS-parsable argument. */
  color?: string;
  /** The animation direction of the icon, left or right. */
  direction?: 'left' | 'right';
  /** The vertical distance between the lines. Small (sm), medium (md) or large (lg). */
  distance?: 'sm' | 'md' | 'lg';
  /** The duration of the animation. Can be set to zero if no animation is desired. */
  duration?: number;
  /** A valid `transition-timing-function` CSS value, for example 'ease-out'. */
  easing?: string;
  /** Hides the default browser focus style. */
  hideOutline?: boolean;
  /** An ARIA label to improve accessibility. */
  label?: string;
  /** A callback which receives a single boolean argument, indicating if the icon is toggled. */
  onToggle?: (toggled: boolean) => any;
  /** Specifies if the icon bars should be rounded. */
  rounded?: boolean;
  /** A number between 12 and 48, which sets the size of the icon. */
  size?: number;
  /** A way to provide your own state action. Has to be used together with a state value (the `toggled` prop). */
  toggle?: Dispatch<SetStateAction<boolean>>;
  /** A way to provide your own state value. Can be used together with a state action (the `toggle` prop). */
  toggled?: boolean;
  /** Specifies if the hamburger should be disabled. */
  disabled?: boolean;
  /** Specifies if the hamburger should run animation when mounted. */
  animateOnMount?: boolean;
}

Advanced Configuration Examples:

import Hamburger from "hamburger-react";

function CustomizedHamburger() {
  const [isOpen, setOpen] = useState(false);
  
  return (
    <Hamburger
      toggled={isOpen}
      toggle={setOpen}
      color="#2563eb"
      size={36}
      duration={0.8}
      easing="ease-in-out"
      distance="lg"
      rounded
      direction="right"
      label="Toggle navigation menu"
      hideOutline={false}
      disabled={false}
      animateOnMount={true}
      onToggle={(toggled) => {
        console.log('Menu is now', toggled ? 'open' : 'closed');
        // Additional side effects
      }}
    />
  );
}

Advanced Component Customization

For advanced use cases, the library provides interfaces for extending the base Burger component functionality. Note that the

Burger
component itself is internal and not directly exported, but can be used through custom implementations using the
BurgerProps
interface.

import { CSSProperties, ReactNode } from 'react';

/**
 * Base burger component with custom render function
 */
export interface BurgerProps extends CommonBurgerProps {
  render: (o: RenderOptions) => ReactNode;
  lines?: number;
}

/**
 * Options object passed to custom render functions
 */
export interface RenderOptions {
  barHeight: number;
  barStyles: CSSProperties;
  burgerStyles: CSSProperties;
  handler: () => void;
  isLeft: boolean;
  isToggled: boolean;
  label: string | undefined;
  margin: number;
  move: number;
  time: number;
  easing: string;
  topOffset: number;
  width: number;
}

Types

All types are defined inline with their usage above. The library uses standard React types:

import { Dispatch, SetStateAction, CSSProperties, ReactNode } from 'react';

Error Handling

The library handles edge cases gracefully:

  • Size values are automatically clamped between 12 and 48 pixels
  • Invalid color values fall back to 'currentColor'
  • Missing state management (no
    toggled
    or
    onToggle
    ) uses internal state
  • Disabled components prevent interaction but maintain visual state
  • Animation duration of 0 disables transitions completely

Accessibility Features

All hamburger components include comprehensive accessibility support:

  • ARIA Attributes:
    aria-label
    and
    aria-expanded
    for screen readers
  • Keyboard Navigation: Enter key support for keyboard-only users
  • Focus Management: Proper focus styles and outline handling
  • Touch Areas: Automatic 48x48 pixel minimum touch area for mobile devices
  • Role Attribution: Proper button role for semantic meaning
  • Customizable Labels: Support for descriptive ARIA labels via
    label
    prop

Performance Characteristics

  • Bundle Size: ~1.5KB when using one hamburger (minified + gzipped)
  • Zero Dependencies: No runtime dependencies beyond React
  • CSS-Only Animations: No JavaScript animations for optimal performance
  • Tree Shaking: Individual components can be imported to reduce bundle size
  • Efficient Rendering: Uses CSS transforms on GPU-accelerated properties
  • Memory Efficient: Minimal state management and no memory leaks