Caption

Overview

Caption displays small supporting text for images, figures, charts, screenshots, tables, media previews, report visuals, product images, and documentation examples. It provides context, source, metadata, or clarification without competing with the main content. Caption keeps supporting notes consistent across Byteion documentation, SaaS dashboards, admin panels, ecommerce back offices, ERP and POS reports, media galleries, analytics pages, and starter-kit screens. Caption is a Typography variant available through @byteion/react and @byteion/vue that renders a variant="caption" with token-based small, muted styling.

Why this exists

Without a shared Caption style, figure notes and image descriptions become inconsistent — one page uses text-xs text-gray-400, another uses text-sm text-muted, a third uses body text with no visual distinction. Sizes vary, muted colors are hardcoded, dark-mode contrast is not tested, and captions drift too close to media or too far apart. Caption unifies all secondary visual annotations into a single, accessible, token-based style with consistent font size, muted color, spacing, and optional truncation that adapts to light mode, dark mode, and branded themes without manual overrides.

Mental model

• Main content explains the message. Headings, body text, and data visualisations carry the primary communication.
• Caption explains the context. It answers "what am I looking at?" or "where does this come from?" — not "what should I do?"
• Caption should be short and secondary. If a note needs more than two lines, consider moving it into the main content or using an Alert.
• Caption should not carry critical instructions alone. Warnings, errors, and essential actions must be visible in the primary content. Caption is for enrichment, not survival.
• Caption pairs with the media or figure it describes. It should be visually attached — close enough that the relationship is obvious without hunting.

Caption vs Text vs Paragraph vs Label

When to use

• Below images or screenshots in documentation
• Below charts or analytics visuals in dashboards
• Below figures in documentation or reports
• Under product or media previews in galleries
• Below report tables as a short source or methodology note
• For source or update metadata attached to visual content
• For short explanatory notes that clarify a visual without distracting from it
• For timestamps, author credit, or data attribution on media assets

When not to use

• Do not use Caption for primary body copy — use Paragraph for standard prose and descriptions.
• Do not use Caption for form labels — use the Label pattern built into Input, Select, and other form components, or render a <label> with text-sm font-medium.
• Do not use Caption for critical warnings or errors — use Alert or Callout with visible tone colors.
• Do not use Caption for long paragraphs — captions over three lines become body copy. If the content is that long, it is not a caption.
• Do not use Caption as a replacement for alt text — alt describes the image for assistive technology; Caption provides visible context.
• Do not use Caption as a Badge or Alert replacement — badges show compact status, alerts show contextual messages. Caption is neither.
• Do not use Caption inside buttons — button labels should be text-sm font-medium or larger.

Basic example

A minimal Caption below a figure. The <figcaption> tag semantically ties the caption to its figure.

Figure and media captions

When a caption describes an image, screenshot, or media item, wrap both in a <figure> and use <figcaption> for the caption. This preserves the semantic relationship.

Screenshot caption

Media preview caption

Chart and table captions

Charts and tables often need a source note, update timestamp, or methodology disclaimer below the visual.

Chart caption

Table caption

A caption below a table acts as a table note without adding a row to the table itself.

All prices in USD. Billed monthly. Enterprise plans have custom pricing.

Variants and sizing

Caption intentionally uses a small, muted style. It should support the content, not compete with headings, labels, or paragraphs. The variant applies text-xs text-muted-foreground for a compact, secondary appearance. Other text styles — muted, body, code, kbd — are available through the Typography component and documented on the Text page.

Truncation

Caption supports optional truncation through the shared Typography schema. When truncate is set to true, the caption is clipped to a single line with an ellipsis overflow.

• Use truncation for media cards, table notes, product gallery items, or constrained dashboard widgets where space is tight.
• Do not truncate captions when users need the full source, disclaimer, or compliance note — use wrapping instead.
• Always pair truncated captions with a Tooltip or expandable area when the full text is essential.

Anatomy

1. Media or content — image, chart, screenshot, table, or product preview
2. Spacing — consistent gap between the media and the caption, typically mt-2 or mt-3
3. Caption text — text-xs text-muted-foreground (or variant="caption" in React/Vue)
4. Truncation indicator (optional) — ellipsis overflow for constrained layouts

Usage guidelines

• Keep captions close to their media. The visual gap should be smaller than the gap to surrounding content so the relationship is clear.
• Keep captions under three lines. If the text is longer, it is not a caption — promote it to body text or an Alert.
• Use text-muted-foreground for the secondary appearance. Do not use text-gray-400 or other hardcoded colors.
• Prefer <figcaption> inside <figure> when the caption describes a specific media item. Use a plain <p> or <div> for free-standing notes below tables or widgets.
• Avoid essential instructions in caption text. If the information is critical, put it in the main content.

Do and Don't

Accessibility

• No keyboard behavior by itself. Caption is purely presentational text. It does not require focus or interaction.
• Use semantic <figcaption> inside <figure> when the caption describes an image, chart, screenshot, or figure. Assistive technology uses the <figcaption> to label the figure.
• Keep alt text and caption text distinct. Alt text describes the image for assistive technology. Caption provides visible context, source, or explanation. They can overlap but should not be identical — if they are, one is redundant.
• Do not put essential information only in a tiny or muted caption. Users with low vision or high-contrast settings may overlook small, low-contrast text. If the information is critical, promote it to the primary content.
• Keep contrast readable in light mode, dark mode, and branded themes. The text-muted-foreground token is designed to meet WCAG AA when used on bg-background and bg-card surfaces.
• Links inside captions must remain visually identifiable (underline or distinct color) and keyboard accessible.

Customization

Caption should be customized through typography and spacing tokens, not one-off style overrides:

• Font size — text-xs is the standard. Use text-[11px] only when constrained by dense layouts.
• Line height — leading-relaxed or leading-normal depending on line count.
• Color — text-muted-foreground for secondary appearance.
• Spacing — mt-2 or mt-3 between media and caption.
• Max width — constrain with max-w-prose or max-w-md when the caption should not stretch full-width.
• Truncation — truncate for constrained card layouts.

HTML example

<figure class="rounded-xl border border-border bg-card p-4">
  <img src="chart.png" alt="Monthly revenue chart for Q2 2026"
    class="rounded-lg w-full" />
  <figcaption class="mt-2 text-xs text-muted-foreground">
    Revenue by month, Jan–Jun 2026. Data from Stripe. Updated daily.
  </figcaption>
</figure>

<!-- Standalone caption below a table -->
<table class="min-w-full border-collapse">
  <!-- table content -->
</table>
<p class="mt-2 text-xs text-muted-foreground">
  All prices in USD. Billed monthly.
</p>

React example

import { Typography } from '@byteion/react';

export default function ChartCaption() {
  return (
    <figure className="space-y-2">
      <img src="/charts/revenue.png" alt="Revenue chart Q2 2026"
        className="rounded-xl border border-border" />
      <figcaption>
        <Typography variant="caption">
          Revenue by month, Jan–Jun 2026. Data from Stripe.
        </Typography>
      </figcaption>
    </figure>
  );
}

Vue example

<script setup lang="ts">
import { Typography } from '@byteion/vue';
</script>

<template>
  <figure class="space-y-2">
    <img src="/charts/revenue.png" alt="Revenue chart Q2 2026"
      class="rounded-xl border border-border" />
    <figcaption>
      <Typography variant="caption">
        Revenue by month, Jan–Jun 2026. Data from Stripe.
      </Typography>
    </figcaption>
  </figure>
</template>

API Reference

Caption is used through the Typography component with variant="caption". Below are the relevant props from the shared Typography schema:

Developer tips

• Keep captions close to the content they describe. Use mt-2 or mt-3 between media and caption — less than the margin to surrounding elements.
• Use alt text for image meaning and Caption for visible context. Alt text is for screen readers; Caption is for all users. They complement each other.
• Keep captions short. One to two lines is ideal. If it needs three or more, move the content into the body text.
• Test mobile wrapping. A two-line caption on desktop may wrap to four lines on a narrow screen.
• Avoid hiding important instructions in caption text. Users scanning the page may skip the small muted text entirely.
• Test dark mode contrast. The text-muted-foreground token adapts automatically, but verify against bg-card and colored media backgrounds.

Common mistakes

• Using Caption instead of Label — form fields need a visible, medium-weight label, not small muted text.
• Using Caption instead of alt text — both are needed. One does not replace the other.
• Writing long paragraphs as captions — if the text exceeds three lines, it is body copy, not a caption.
• Making critical warnings tiny and muted — errors and warnings belong in Alert or Callout, not in caption text.
• Hardcoding muted colors — text-gray-400 or text-zinc-500 breaks in dark mode. Use text-muted-foreground.
• Not testing mobile wrapping — short captions on desktop can overflow or wrap awkwardly on mobile.
• Using Caption inside buttons — button labels need font-medium weight and adequate size. Caption is too small for buttons.

Production usage tips

• Verify captions are attached to the correct media or figure. A caption that drifts visually from its image or chart confuses the reader.
• Test caption wrapping on mobile. What fits on one line on desktop may need three on a small screen. Ensure the visual relationship is preserved.
• Test dark mode and branded themes. The text-muted-foreground token must remain readable (WCAG AA 4.5:1) against both bg-background and bg-card.
• Confirm source and update metadata is accurate. Outdated timestamps or incorrect data sources undermine trust.
• Keep React and Vue output aligned with the core Typography schema. The variant and truncate props behave identically across frameworks.
• Do not use Caption for dynamic tooltip-style text. Use Tooltip for hover-revealed information.

Premium examples

Advanced patterns available in Pro extend Caption into richer data context and application-specific annotations.

• Chart caption with source and update time — revenue chart followed by text-xs text-muted-foreground with "Data from Stripe. Updated 5m ago."
• Screenshot caption for documentation pages — figure with numbered callout labels and a caption explaining each numbered area.
• Media card caption with upload metadata — product image with "Uploaded by Jane Doe, 2 days ago" in the caption area of a card.
• Ecommerce gallery caption with product context — product image panel with "Shown in Charcoal. Also available in Navy and Forest."
• Report figure caption with dataset source — bar chart with "Source: US Census Bureau, 2025. Methodology: weighted regression."
• Table note caption for analytics reports — data table followed by "Some values are estimated. Contact support for raw data."
• Dashboard KPI note — metric card with a small caption reading "Updated every 30 minutes" below the KPI value and trend.

Related components

• Text — body copy, helper text, metadata, code, and keyboard labels
• Paragraph — readable body copy for descriptions, documentation, and prose
• Inline Code — short code fragments inside prose
• Card — surface container that may pair an image or figure with its caption
• Avatar — user avatars that may include a caption-style name or metadata
• Badge — compact status and count labels (not a caption replacement)

API Reference

Related components

Pair this component with adjacent Byteion primitives from the same workflow: form controls for data entry, feedback components for validation, and layout primitives for spacing.

Runtime events

Byteion keeps framework APIs idiomatic: HTML uses DOM custom events, React uses callback props, and Vue uses emitted events / v-model updates.

Remote / AJAX