article
Self-contained, independently distributable content such as blog posts, news articles, forum posts, product cards, or user comments.
Usage
Use the <article> element for content that:
- Makes sense on its own, outside the context of the page
- Could be syndicated or shared independently (RSS, social media)
- Represents a complete, self-contained composition
Common uses include blog posts, news articles, product cards, forum posts, comments, and widgets.
Examples
Default
Basic article with header and content.
Default article
<article> <header> <h2>Article Title</h2> <p>Published on <time datetime="2024-01-15">January 15, 2024</time></p> </header> <p>This is the main content of the article.</p> <footer> <p>Written by Jane Doe</p> </footer></article>.blog
Optimized for long-form reading with constrained width (65ch).
Blog article
<article class="blog"> <header> <h2>How to Write Better Articles</h2> <p><time datetime="2024-01-15">January 15, 2024</time> in Writing</p> </header> <p>Writing compelling articles requires understanding your audience, structuring your thoughts clearly, and revising thoroughly.</p> <footer> <p>By Jane Doe | 5 min read</p> </footer></article>.card
Card-style article with border, background, and padding.
Card article
<article class="card"> <h3>Product Feature Update</h3> <p>We have released new features that improve performance by 40% and add dark mode support.</p> <a href="#">Read more</a></article>.feature
Hero-style feature article with centered header.
Feature article
<article class="feature"> <header> <h2>Introducing Vanilla Breeze</h2> <p>A layered HTML component system for modern web development</p> </header> <p>Build accessible, performant websites with native HTML elements enhanced through progressive CSS styling.</p></article>.compact
Compact list-item style for article listings.
Compact article
<article class="compact"> <img src="thumb.jpg" alt="Thumbnail" /> <section> <h3>Getting Started with CSS Grid</h3> <p>Learn the fundamentals of CSS Grid layout.</p> </section></article>.nested
Nested articles for comments and replies with indentation.
Nested article
<article> <header> <strong>User123</strong> <time datetime="2024-01-15T10:30">10:30 AM</time> </header> <p>This is a great article! Thanks for sharing.</p> <article class="nested"> <header> <strong>Author</strong> <time datetime="2024-01-15T11:00">11:00 AM</time> </header> <p>Thank you for the kind words!</p> </article></article>data-numbered
Academic-style auto-numbering for headings, figures, and tables. CSS counters automatically prefix h2-h4 headings with hierarchical numbers, and prepend "Figure" / "Table" labels to captions.
Auto-numbered article
<article data-numbered> <h2>Origins of Movable Type</h2> <p>Movable type was first developed in China...</p> <h3>Gutenberg's Press</h3> <p>Johannes Gutenberg independently invented...</p> <h2>The Typographic Tradition</h2> <figure> <img src="press.jpg" alt="Historical printing press" /> <figcaption>A reconstructed printing press.</figcaption> </figure></article>data-drop-cap
Adds a large decorative initial letter to the opening paragraph, a convention borrowed from illuminated manuscripts and editorial print design.
Drop cap article
<article data-drop-cap> <p>When the first rays of morning light crept through the cathedral windows, they illuminated row upon row of hand-set lead type...</p></article>data-prose
Automatically floats images that appear inside paragraphs to the inline-end, sized to half the content width. Ideal for markdown or CMS-generated content where images are placed directly within paragraph text.
Prose mode article
<article data-prose> <p> <img src="meadow.jpg" alt="Wildflowers" /> The alpine meadows above the treeline host an extraordinary diversity of wildflowers during the brief summer season... </p></article>data-highlights
Enables Medium-style text highlighting and private notes. Select text to see a floating toolbar with color swatches. Click an existing highlight to change color, add a note, or remove it. Highlights persist in localStorage.
Article with highlights
<article data-highlights> <p>Select any text in this article to highlight it. Choose a color from the toolbar that appears above your selection.</p></article>data-highlights (custom colors)
Use data-highlights-colors to provide a custom palette and define matching --highlight-{name} custom properties.
Custom highlight colors
<article data-highlights data-highlights-colors="yellow,green,blue,pink"> <!-- Define custom property for each color name --> <style> article { --highlight-yellow: #fef08a; } </style> <p>Custom highlight palette.</p></article>data-highlights (readonly)
Add data-highlights-readonly to render stored highlights without allowing new ones.
Readonly highlights
<article data-highlights data-highlights-readonly> <p>Renders stored highlights without allowing new ones.</p></article>Variants
| Class | Description |
|---|---|
.blog |
Long-form reading layout with 65ch max-width, spaced header/footer |
.card |
Card styling with border, background, padding, and rounded corners |
.feature |
Grid layout with centered header for hero-style content |
.compact |
Flexbox horizontal layout for article listings |
.nested |
Indented with left border for threaded comments/replies |
data-numbered |
Academic-style auto-numbering for h2-h4 headings, figures, tables, and code listings |
data-drop-cap |
Large decorative first letter on the opening paragraph |
data-prose |
Auto-float images inside paragraphs for markdown/CMS content |
data-highlights |
Text highlighting and private notes with localStorage persistence |
Accessibility
- Articles create landmark regions that screen readers can navigate to
- Always include a heading (h1-h6) to label the article content
- Use
<header>and<footer>within articles for structured metadata - Include
<time>elements withdatetimeattributes for publication dates - Nested articles maintain proper heading hierarchy (avoid skipping levels)
Highlights API
The data-highlights attribute activates a JavaScript controller that provides a programmatic API for managing highlights.
Attributes
| Attribute | Description |
|---|---|
data-highlights |
Enables highlighting. Optional string value becomes the localStorage key suffix (default: page pathname). |
data-highlights-colors |
Comma-separated color names. Each maps to a --highlight-{name} CSS custom property. Default: yellow,green,blue,pink |
data-highlights-readonly |
Renders stored highlights but disables creating new ones. |
Events
| Event | Detail | Description |
|---|---|---|
highlights:added |
{ id, text, color, note } |
Fired when a new highlight is created |
highlights:removed |
{ id } |
Fired when a highlight is deleted |
highlights:note-changed |
{ id, note } |
Fired when a note is added or edited |
highlights:clicked |
{ id } |
Fired when an existing highlight is clicked |
JavaScript API
Programmatic control
import { initHighlights } from 'vanilla-breeze'; const ctrl = initHighlights(document.querySelector('[data-highlights]'));ctrl.getHighlights(); // Array of highlight objectsctrl.removeHighlight(id); // Remove by IDctrl.clearAll(); // Remove allctrl.exportHighlights(); // JSON stringctrl.importHighlights(json); // Restore from backupctrl.destroy(); // Cleanup listeners/code-block <h3>CSS Custom Properties</h3> <table class="props-table"> <thead> <tr> <th>Property</th> <th>Default</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td><code>--highlight-yellow</code></td> <td><code>#fef08a</code></td> <td>Yellow highlight color</td> </tr> <tr> <td><code>--highlight-green</code></td> <td><code>#bbf7d0</code></td> <td>Green highlight color</td> </tr> <tr> <td><code>--highlight-blue</code></td> <td><code>#bfdbfe</code></td> <td>Blue highlight color</td> </tr> <tr> <td><code>--highlight-pink</code></td> <td><code>#fbcfe8</code></td> <td>Pink highlight color</td> </tr> <tr> <td><code>--highlight-toolbar-bg</code></td> <td><code>var(--color-surface-raised)</code></td> <td>Toolbar background</td> </tr> <tr> <td><code>--highlight-toolbar-shadow</code></td> <td><code>var(--shadow-m)</code></td> <td>Toolbar box shadow</td> </tr> </tbody> </table> <h3>Progressive Enhancement</h3> <ul> <li><strong>No JS</strong> — <code>data-highlights</code> is inert; article renders normally</li> <li><strong>No CSS Highlight API</strong> — falls back to <code><mark></code> wrapping</li> <li><strong>No localStorage</strong> — highlights work for the current session but are not persisted</li> </ul>