caption

The caption element provides a title or description for a table. It is essential for accessibility, helping users understand the purpose and content of the table.

Description

The <caption> element must be the first child of a <table> element. It provides a programmatic association between the table and its description, which is announced by screen readers when users navigate to the table.

Vanilla Breeze styles captions with muted text color and medium font weight, positioned at the top of the table with left alignment.

When to Use

  • Every data table: All tables containing meaningful data should have a caption
  • Table identification: When multiple tables appear on a page
  • Context setting: To explain what data the table contains
  • Time-sensitive data: To indicate the date or period the data represents

When Not Required

  • Decorative tables: Purely presentational tables (though these should be avoided)
  • Tables with adjacent headings: If a heading immediately precedes the table, use aria-labelledby instead

Basic Example

Place the caption as the first child of the table element.

Employee Directory - January 2024
Name Department Email
Alice Johnson Engineering alice@example.com
Bob Smith Design bob@example.com
<table> <caption>Employee Directory - January 2024</caption> <thead> <tr> <th scope="col">Name</th> <th scope="col">Department</th> <th scope="col">Email</th> </tr> </thead> <tbody> <!-- Table data --> </tbody> </table>

Caption Content

Captions can contain additional elements for richer descriptions.

With Description

Quarterly Sales Report
Data from January - March 2024
Product Q1 Sales Revenue
Widget Pro 1,250 $62,500
Gadget Plus 890 $44,500

With Data Source

Population by Region
Source: Census Bureau, 2023
Region Population Change
Northeast 55,982,803 +0.2%
Midwest 68,985,454 +0.4%

Accessibility

  • Required for data tables: WCAG 2.1 Success Criterion 1.3.1 requires tables to be programmatically identifiable
  • Screen reader announcement: When a user navigates to a table, the caption is announced first, providing context
  • Be descriptive: Write captions that explain what data the table contains, not just "Table 1"
  • Include date/time context: If data is time-sensitive, include the relevant period in the caption

Alternative: aria-labelledby

If a heading immediately precedes the table, you can use aria-labelledby instead of a caption:

Monthly Sales Data

Month Sales
January $10,500
February $12,300
<h3 id="sales-heading">Monthly Sales Data</h3> <table aria-labelledby="sales-heading"> <!-- Table content without caption --> </table>

Styling

Vanilla Breeze applies the following styles to captions:

Property Value Description
padding var(--size-s) var(--size-m) Consistent spacing with table cells
text-align start Left-aligned (RTL-aware)
font-weight 500 Medium weight for emphasis
color var(--color-text-muted) Muted to differentiate from data

Related Elements

  • <table> - Parent container (caption must be first child)
  • <thead> - Header group that follows caption
  • <th> - Header cells that provide column/row context