Skip to content

Share preview

How a page appears when shared, as a search result and social card, with a width meter.

<div class="cap-serp" role="group" aria-label="Search result preview" id="sp-serp">
  <p class="cap-serp-url">example.com › blog › why-the-editor-waits</p>
  <p class="cap-serp-title">Why the editor waits before it publishes</p>
  <p class="cap-serp-description">A failing required check blocks a publish, and a held one says who holds it and until when. Here is what the wait buys.</p>
</div>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/share-preview.css";
import { serpTextWidth, serpReading } from "capsomer/behavior/share-preview";

Usage

<div class="cap-serp" role="group" aria-label="Search result preview">
  <p class="cap-serp-url">example.com › blog › post</p>
  <p class="cap-serp-title">Title</p>
  <p class="cap-serp-description">Description</p>
  <p class="cap-serp-note">Optional note</p>
</div>

<div class="cap-og-card" role="group" aria-label="Social card preview">
  <div class="cap-og-card-image"><img src="..." alt="..." width="1200" height="630" /></div>
  <div class="cap-og-card-body">
    <p class="cap-og-card-host">example.com</p>
    <p class="cap-og-card-title">Title</p>
    <p class="cap-og-card-description">Description (optional)</p>
  </div>
  <p class="cap-og-card-note">Optional note</p>
</div>

Examples

Search result, with a note that it will be cut

<div class="cap-serp" role="group" aria-label="Search result preview" id="sp-serp-cut">
  <p class="cap-serp-url">example.com › blog › why-the-uptime-strip-counts-gaps</p>
  <p class="cap-serp-title">Why the uptime strip counts gaps and does not average them away in the …</p>
  <p class="cap-serp-description">An average of 99.9 percent hides a four hour hole. The strip draws each gap, so the hole is the first thing you see …</p>
  <p class="cap-serp-note">Title and description will be truncated. The limits are approximate: search engines cut by pixel width, not by character count.</p>
</div>

Social card

<div class="cap-og-card" role="group" aria-label="Social card preview" id="sp-og">
  <div class="cap-og-card-image">
    <svg viewBox="0 0 1200 630" role="img" aria-label="The post's cover: a rising line over a grid"><rect width="1200" height="630" fill="oklch(0.55 0.12 300)"/><path d="M60 520 L300 400 L520 450 L760 250 L1140 120" fill="none" stroke="#fff" stroke-width="14" stroke-linecap="round" stroke-linejoin="round"/></svg>
  </div>
  <div class="cap-og-card-body">
    <p class="cap-og-card-host">example.com</p>
    <p class="cap-og-card-title">Why the editor waits before it publishes</p>
    <p class="cap-og-card-description">A failing required check blocks a publish. Here is what the wait buys.</p>
  </div>
</div>

Social card with a note, no description, in a narrow space

<div class="share-preview-narrow-box">
  <div class="cap-og-card" role="group" aria-label="Social card preview" id="sp-og-note">
    <div class="cap-og-card-image">
      <svg viewBox="0 0 600 600" role="img" aria-label="The site mark, used because this post has no cover"><rect width="600" height="600" fill="oklch(0.9 0.02 300)"/><circle cx="300" cy="300" r="120" fill="oklch(0.55 0.12 300)"/></svg>
    </div>
    <div class="cap-og-card-body">
      <p class="cap-og-card-host">example.com</p>
      <p class="cap-og-card-title">A title long enough to wrap onto a second line in a narrow card</p>
    </div>
    <p class="cap-og-card-note">No cover set, so this shares as the site mark. A generated card may still replace it.</p>
  </div>
</div>

Width meters: a title that fits, and one Google cuts off

<div data-mount="width"></div>

API reference

SerpPreview

PropTypeRequiredDoes
urlstringYesThe address as a search result writes it: "example.com › blog › post".
titleReactNodeYes
descriptionReactNodeYes
noteReactNodeSaid under the result, for example that the title will be cut.
labelstring

OgCardPreview

PropTypeRequiredDoes
imageReactNodeYesAn img (alt text set by the app) or an svg. Drawn in a box at the card's 1200 x 630 shape.
hoststringYes
titleReactNodeYes
descriptionReactNode
noteReactNodeSaid under the card, for example that the site mark stands in for a missing cover.
labelstring

SerpWidthMeter

PropTypeRequiredDoes
labelReactNodeYesThe meter's name: "Search title width".
textstringYesThe text as the result will show it.
partSerpPartWhich part of a result it is: its font and limit. Default "title".
limitnumberThe width past which it is cut, in pixels. Default Prelum's for the part.
measure(text: string) => number | nullA width of the app's own (a canvas measure in the real font): null while measuring. Default Prelum's serpWidth, which needs no browser, so a server render shows the number.
size"sm" | "md" | "lg"

Functions

FunctionSignatureDoes
serpTextWidth(text: string, part: SerpPart): numberThe text's width in whole pixels, from Arial's advance widths at the part's size.
serpReading(text: string, px: number | null, limit: number): SerpReadingThe meter's words for a width. px null is still being measured.

Parts and data attributes

ClassIs
.cap-og-cardits own class
.cap-og-card-bodyits own class
.cap-og-card-descriptionits own class
.cap-og-card-hostits own class
.cap-og-card-imageits own class
.cap-og-card-noteits own class
.cap-og-card-titleits own class
.cap-serpthe root
.cap-serp-descriptiona part
.cap-serp-notea part
.cap-serp-titlea part
.cap-serp-urla part

Accessibility

Nothing in a preview takes focus. The page's order is the reading order.

  • Text is --text, --muted and --accent-text on --surface; each pair is in the contrast report.
  • The card image must carry its own alt text. When the image is a stand-in, say so in the alt text and in the note, as the site admin does.