Hamburger Menu

Overview

The Hamburger Menu is an interactive toggle button typically used in mobile navigation headers to expand or collapse a drawer or sidebar. It renders as three horizontal bars in its resting state and animates into an alternative glyph — an X, arrow, plus, or minus — when the active state is set to true. The styling is provided by useHamburgerMenuRecipe(), which exposes color, size, animation, and active axes.

The Hamburger Menu recipe integrates directly with the default design tokens preset and generates type-safe utility classes at build time with zero runtime CSS. Visual state (open/closed) is driven by modifier classes, so transitions are pure CSS.

Why use the Hamburger Menu recipe?

The Hamburger Menu recipe helps you:

• Ship faster with sensible defaults: Get 3 colors, 3 sizes, and 7 open-state animations out of the box with a single composable call.
• Keep transitions smooth: CSS-driven transforms with staggered timings produce polished open-close animations without JavaScript.
• Swap animations freely: Pick the glyph that fits your UI — X for close, arrows for directional menus, plus/minus for expand/collapse affordances.
• Maintain consistency: Compound variants ensure every color adapts correctly across light and dark modes.
• Customize without forking: Override base styles, default variants, or filter out options you don't need — all through the options API.
• Stay type-safe: Full TypeScript support means your editor catches invalid color, size, animation, or active values at compile time.

Usage

import { styleframe } from 'virtual:styleframe';
import { useHamburgerMenuRecipe } from '@styleframe/theme';

const s = styleframe();

const hamburgerMenu = useHamburgerMenuRecipe(s);

export default s;

import { useState } from "react";
import { hamburgerMenu } from "virtual:styleframe";

interface HamburgerMenuProps {
    color?: "light" | "dark" | "neutral";
    size?: "sm" | "md" | "lg";
    animation?:
        | "close"
        | "arrow-up"
        | "arrow-down"
        | "arrow-left"
        | "arrow-right"
        | "minus"
        | "plus";
    label?: string;
    onToggle?: (active: boolean) => void;
}

export function HamburgerMenu({
    color = "neutral",
    size = "md",
    animation = "close",
    label = "Toggle menu",
    onToggle,
}: HamburgerMenuProps) {
    const [active, setActive] = useState(false);
    const toggle = () => {
        const next = !active;
        setActive(next);
        onToggle?.(next);
    };
    return (
        <button
            type="button"
            className={hamburgerMenu({
                color,
                size,
                animation,
                active: active ? "true" : "false",
            })}
            aria-expanded={active}
            aria-label={label}
            onClick={toggle}
        >
            <span className="hamburger-menu-inner" />
        </button>
    );
}

<script setup lang="ts">
import { computed, ref } from "vue";
import { hamburgerMenu } from "virtual:styleframe";

const {
    color = "neutral",
    size = "md",
    animation = "close",
    label = "Toggle menu",
} = defineProps<{
    color?: "light" | "dark" | "neutral";
    size?: "sm" | "md" | "lg";
    animation?:
        | "close"
        | "arrow-up"
        | "arrow-down"
        | "arrow-left"
        | "arrow-right"
        | "minus"
        | "plus";
    label?: string;
}>();

const active = ref(false);
const classes = computed(() =>
    hamburgerMenu({
        color,
        size,
        animation,
        active: active.value ? "true" : "false",
    }),
);
</script>

<template>
    <button
        type="button"
        :class="classes"
        :aria-expanded="active"
        :aria-label="label"
        @click="active = !active"
    >
        <span class="hamburger-menu-inner" />
    </button>
</template>

Colors

The Hamburger Menu recipe includes 3 color variants: light, dark, and neutral. The color value drives the bar color via the button's color CSS property (the inner bars use currentColor).

The neutral color adapts automatically: dark bars in light mode, light bars in dark mode, making it the safest default.

Color Reference

Sizes

Three size variants control the bar dimensions (width, height, vertical offset) and the button's padding:

Animations

Seven animation values control how the bars morph when active is true. When active is false the button renders as three static horizontal bars regardless of which animation is selected.

Close

The classic hamburger → X transition. Top and bottom bars pivot in and the middle bar fades out, forming an X.

Arrow Left / Right

Bars scale down and rotate to form a ‹ (left) or › (right). Useful for drawers that slide horizontally.

Arrow Up / Down

Like the horizontal arrows, but the entire icon rotates ±90° so the arrow points up or down.

Minus

All bars collapse into a single horizontal line — a subtle transition that suggests "collapsed" rather than "closed".

Plus

The middle bar stays horizontal while the top bar rotates 90° to form a vertical bar, producing a + glyph. The bottom bar fades out. Pairs well with expand/collapse interactions.

Active State

The active axis is a boolean ("true" / "false") that drives the open-state transform. Consumers are responsible for tracking the open state and toggling it on click.

Anatomy

The Hamburger Menu renders as a single <button> element with one child <span> that represents the middle bar; the span's ::before and ::after pseudo-elements render the top and bottom bars:

<button class="hamburger-menu(...)" aria-expanded="false" aria-label="Toggle menu">
    <span class="hamburger-menu-inner"></span>
</button>

Accessibility

• Expose the toggle state. Always set aria-expanded="true|false" on the button so assistive technologies know whether the menu is open.
• Provide an accessible name. Set aria-label="Toggle menu" (or localized equivalent) since the button has no visible text.
• Focus visibility. The recipe applies a keyboard-only focus ring via &:focus-visible using @color.primary. Do not remove it.
• Hit target size. Default md padding (@0.5) combined with 20px bar width yields a minimum 24px × 24px hit target; pair with additional padding on the parent container to reach the WCAG 2.1 44px target on mobile.
• Disable carefully. The recipe supports :disabled styling; when disabled, pointer events are ignored and opacity drops to 0.5.

<!-- Correct: accessible hamburger menu -->
<button
    class="hamburger-menu(...)"
    type="button"
    aria-expanded="true"
    aria-controls="main-nav"
    aria-label="Close menu"
>
    <span class="hamburger-menu-inner"></span>
</button>

Customization

Overriding Defaults

The useHamburgerMenuRecipe composable accepts an optional second argument to override any part of the recipe configuration. Overrides are deep-merged with the defaults:

import { styleframe } from 'virtual:styleframe';
import { useHamburgerMenuRecipe } from '@styleframe/theme';

const s = styleframe();

const hamburgerMenu = useHamburgerMenuRecipe(s, {
    defaultVariants: {
        color: 'dark',
        size: 'lg',
        animation: 'arrow-left',
        active: 'false',
    },
});

export default s;

Filtering Variants

If you only need a subset of the available animations, use the filter option to limit which values are generated. This reduces the output CSS:

import { styleframe } from 'virtual:styleframe';
import { useHamburgerMenuRecipe } from '@styleframe/theme';

const s = styleframe();

// Only generate the close animation in all three colors
const hamburgerMenu = useHamburgerMenuRecipe(s, {
    filter: {
        animation: ['close'],
    },
});

export default s;

API Reference

useHamburgerMenuRecipe(s, options?)

Creates the hamburger menu recipe with button, bar, and animation styling.

Parameters:

Variants:

Learn more about recipes →

Best Practices

• Track active state in the consumer. The recipe provides the CSS; the open/closed state lives in your app (React useState, Vue ref, etc.).
• Pair aria-expanded with active. Mirror the active prop onto aria-expanded so screen readers announce state changes.
• Pick the animation that matches the affordance. Use close for a classic menu toggle, arrow-* for directional drawers, plus/minus for expand/collapse interactions.
• Prefer neutral color. It adapts to light and dark modes automatically; only reach for light or dark when the button sits on a surface that conflicts with the user's theme.
• Keep the HTML minimal. The recipe expects exactly one .hamburger-menu-inner child — don't wrap it or add siblings, or the ::before/::after pseudo-elements won't line up.