Vanilla Breeze

brand-mark

Web component for brand/logo display with automatic dark/light logo switching. Use in headers, footers, and anywhere you need consistent brand representation.

Overview

The <brand-mark> element provides a consistent way to display your brand name and logo. It handles typography, spacing, link styling, and automatic dark/light logo switching.

Progressive enhancement: without JavaScript, text content always renders. With JavaScript, the component injects images from the src attribute and observes color mode changes to swap between light and dark logos.

Attributes

Attribute Values Default Description
src URL - Path to logo image (SVG preferred). Used in light mode or as the default when no src-dark is provided.
src-dark URL - Path to dark-mode logo. Auto-switches based on prefers-color-scheme and data-mode attribute.
src-compact URL - Path to compact/icon logo for narrow contexts (e.g., mobile headers).
alt string text content Alt text for the logo image. Defaults to the element's text content.
wordmark boolean - Show text alongside the image logo. Without this, only the image is shown.
height number (px) - Explicit pixel height for the logo image.
data-size s, l, xl - Adjust brand mark size
data-stack boolean - Stack logo and text vertically

Basic Usage

Wrap your brand name in the element, optionally with a logo image. Use an empty alt on the image since the brand name provides the text alternative.

Image Logo via src

Use the src attribute to load a logo image. The JS enhancement injects an <img> element automatically. Without JS, the text content renders as a fallback — this is progressive enhancement.

By default, only the image is shown. The text content becomes the alt text or aria-label.

Image + Wordmark

Add the wordmark attribute to show the brand name text alongside the logo image.

Use height to control the image size explicitly. The CSS token --brand-mark-height can also be set by themes.

Dark/Light Logo Switching

Use src-dark to provide an alternate logo for dark mode. The component automatically switches between logos based on the system prefers-color-scheme preference and the VB data-mode attribute on <html>.

The switching happens reactively — toggling the color mode in the settings panel or changing the system preference immediately updates the displayed logo with no page reload.

If only src is provided without src-dark, that logo is used in both modes.

Tagline

Nest an <em> or <small> inside <brand-mark> to display a tagline or subtitle. Combine with data-stack for vertical layouts commonly used in footers.

The tagline renders in a smaller, muted font with italic style. It works in both inline and stacked layouts.

Sizes

Use data-size to adjust the brand mark for different contexts.

Stacked Layout

Use data-stack for vertical logo and text arrangement. Useful for centered layouts like login pages or footers.

As a Link

Wrap in an anchor to make the brand mark clickable. The element automatically removes link underlines and adjusts hover states.

In a Header

Common usage in site headers with navigation.

Accessibility

  • When using the src attribute without wordmark, the text content is used as aria-label or image alt
  • When using wordmark, the image gets alt="" (decorative) since the visible text provides the label
  • When manually adding an <img> child, set alt="" since the brand name text provides the text alternative
  • When wrapped in a link, the brand name serves as the link text
  • Ensure sufficient color contrast between brand text and background
  • Focus states are handled automatically when wrapped in a link
  • Without JS, the src attribute has no effect — text content always provides a readable fallback

Content Model

Permitted Content

  • Text (brand name)
  • Optional <img> or <svg> (logo)

Permitted Parents

Any flow content. Commonly placed inside <a>, <header>, or <nav>.

CSS Tokens

TokenDefaultDescription
--brand-mark-height 2rem Height of the logo image (set by themes)

Related
↑