optimists — Component Library

Component Docs

Live previews, prop tables, and usage guides for every component in the @optimists/ui package. Figma design file: LmuR42ZKVVmfysQRtJXQAb

View Demo →13 components

Available on npm

Use these components to share some positive news.

@optimists/ui is an open-source React component library built for publishers who want to surface good-news stories with clarity and style.

Install

npm i @optimists/ui

Quick start

JSX

import { CardHero, StatHero, PullQuote } from '@optimists/ui';

export default function NewsPage() {
  return (
    <CardHero
      headline="Scientists discover ocean cleans itself faster than thought"
      deck="New research shows micro-organisms breaking down plastic at record rates."
      sectionTag="Environment"
      readTime="3 min read"
    />
  );
}

View on npmjs.com ↗

Components

13 components — live previews, props, and usage guides.

CardFeature

Half-page 360px story card with an optional image area, author metadata, and a category accent strip. Use for secondary feature stories in a 2–3 column grid.

Preview — Science

Teal accent with default white background.

📸 Photo

SCIENCE

Mon 25 May

4 min read

New Research Confirms Why Your Coffee Actually Makes You More Productive

MIT researchers have pinpointed the exact neural pathway caffeine activates to boost sustained concentration.

Marcus Chen

Code

JSX

<CardFeature
  headline="New Research Confirms Why Your Coffee Actually Makes You More Productive"
  description="MIT researchers have pinpointed the neural pathway caffeine activates."
  author="Marcus Chen"
  date="Mon 25 May"
  readTime="4 min read"
  category="SCIENCE"
  accentColor="#A2CFD0"
  categoryTextColor="#192A56"
/>

Props reference

Props

Prop	Type	Required	Default	Description
headline	string	yes	—	Story headline
description	string	yes	—	Short standfirst / teaser
author	string	yes	—	Author display name

Usage

## Usage

JSX

import { CardFeature } from '@optimists/ui';

Display in a `grid-cols-2` or `grid-cols-3` layout. A single `accentColor` drives the top strip, category chip background, and author avatar badge simultaneously, making colour theming straightforward. Supply `imageSrc` to add a top image panel.

💡

Designed at approximately 360px height. The author avatar uses the first character of `author`.

RankList

Top-5 ranked infographic list with flag/icon emoji, item labels, and value pills. Use for "best of" rankings, league tables, or fact-check comparisons.

Preview — Happiness Index

Green header with alternating teal row stripes.

TOP 5 HAPPIEST COUNTRIES

World Happiness Report 2024 ranking

🇫🇮

Finland

7.74

🇩🇰

Denmark

7.58

🇮🇸

Iceland

7.53

🇸🇪

Sweden

7.34

🇮🇱

Israel

7.34

Source: UN World Happiness Report, 2024

Code

JSX

<RankList
  title="TOP 5 HAPPIEST COUNTRIES"
  subtitle="World Happiness Report 2024 ranking"
  entries={[
    { flag: '🇫🇮', item: 'Finland', value: '7.74' },
    { flag: '🇩🇰', item: 'Denmark', value: '7.58' },
    { flag: '🇮🇸', item: 'Iceland', value: '7.53' },
    { flag: '🇸🇪', item: 'Sweden', value: '7.34' },
    { flag: '🇮🇱', item: 'Israel', value: '7.34' },
  ]}
  source="Source: UN World Happiness Report, 2024"
  headerBgColor="#153B2E"
  titleColor="#C1ECC6"
/>

Props reference

Props

Prop	Type	Required	Default	Description
title	string	yes	—	Header label, e.g. "TOP 5 COFFEE PRODUCERS"
subtitle	string	yes	—	Subheading beneath the title
entries	RankListEntry[]	yes	—	Ranked rows — each has flag, item, and value

Usage

## Usage

JSX

import { RankList } from '@optimists/ui';

Designed at 360px width — pair with `Timeline` or `DataGrid` in the same row. Rank badge opacity decreases from 1st to 5th place automatically based on position. Pass up to 5 entries; more rows are supported but may look crowded.

Timeline

Vertical 4-entry timeline infographic with year badges, event titles, and detail sentences. Use for historical context panels or process flows.

Preview — Internet History

Default styling — grey header, alternating white rows.

THE INTERNET — A TIMELINE

1969

ARPANET goes online

The first message is sent between UCLA and Stanford University

1991

World Wide Web is born

Tim Berners-Lee creates HTML and launches the first website

2004

Social media era begins

Facebook launches, permanently changing how billions of people connect

2023

AI reshapes the web

Large language models transform search, content and creative work forever

Source: Computer History Museum, 2024

Code

JSX

<Timeline
  title="THE INTERNET — A TIMELINE"
  entries={[
    { year: '1969', event: 'ARPANET goes online', detail: 'First message sent between UCLA and Stanford' },
    { year: '1991', event: 'World Wide Web is born', detail: 'Tim Berners-Lee creates HTML' },
    { year: '2004', event: 'Social media era begins', detail: 'Facebook launches' },
    { year: '2023', event: 'AI reshapes the web', detail: 'Large language models transform creative work' },
  ]}
  source="Source: Computer History Museum, 2024"
/>

Props reference

Props

Prop	Type	Required	Default	Description
title	string	yes	—	Header label, e.g. "THE INTERNET — A TIMELINE"
entries	TimelineEntry[]	yes	—	Timeline rows — each has year, event, detail, and optional badge colour
entries[].year	string	yes	—	Year or era label shown in the circular badge

Usage

## Usage

JSX

import { Timeline } from '@optimists/ui';

Designed to be ~360px wide — works well beside `RankList` in a 2–3 column infographic row. Per-entry `badgeColor` lets you colour-code entries (e.g. green for milestones, yellow for key events).

CompareBlock

Full-width side-by-side A vs B comparison card with large stats, descriptions, and icon badges. Use for fact-check or "did you know?" infographic comparisons.

Preview — Medical

Default navy header with white columns.

ISCHEMIC STROKE

HEMORRHAGIC STROKE

🧠

87%

of all strokes are ischemic

Occurs when arteries are blocked by blood clots or gradual build-up of plaque. Most common — and most treatable.

🩸

13%

of strokes, yet 30%+ of deaths

Occurs when a blood vessel breaks. Less common than ischemic but far more likely to be fatal.

Code

JSX

<CompareBlock
  labelA="ISCHEMIC STROKE"
  labelB="HEMORRHAGIC STROKE"
  statA="87%"
  statALabel="of all strokes are ischemic"
  descA="Occurs when arteries are blocked by blood clots or gradual build-up of plaque."
  statB="13%"
  statBLabel="of strokes, yet 30%+ of deaths"
  descB="Occurs when a blood vessel breaks."
  emojiA="🧠"
  emojiB="🩸"
/>

Props reference

Props

Prop	Type	Required	Default	Description
labelA	string	yes	—	Left column header label, e.g. "ISCHEMIC STROKE"
labelB	string	yes	—	Right column header label
statA	string	yes	—	Large stat value for the left column, e.g. "87%"

Usage

## Usage

JSX

import { CompareBlock } from '@optimists/ui';

Full-width component designed at ~746px. Use it once per section — not in a grid. Supply emoji badges (`emojiA`, `emojiB`) to add visual anchors; omit them for a cleaner text-only layout.

WeatherBanner

Full-width editorial weather banner with a large emoji, location, headline, prose, and up to 3 mood pills. Use as a contextual header for weather or wellbeing stories.

Preview — Sunny

Yellow background for bright sunny weather.

☀️

WEATHER

Near Edinburgh, GB

Sunshine and highs of 12°c in sunny Scotland today.

The people and plants are going to be very happy. A glorious day ahead — expect smiles, open windows, and maybe a spontaneous walk.

🌿Plants happy

😊People smiling

🪟Windows open

Code

JSX

<WeatherBanner
  mainEmoji="☀️"
  location="Near Edinburgh, GB"
  headline="Sunshine and highs of 12°c in sunny Scotland today."
  prose="A glorious day ahead — expect smiles and open windows."
  moodPills={[
    { emoji: '🌿', label: 'Plants happy' },
    { emoji: '😊', label: 'People smiling' },
    { emoji: '🪟', label: 'Windows open' },
  ]}
  bgColor="#fce29a"
  categoryBgColor="#192a56"
/>

Props reference

Props

Prop	Type	Required	Default	Description
mainEmoji	string	yes	—	Large weather emoji in the left column, e.g. "☀️"
location	string	yes	—	Location label, e.g. "Near Edinburgh, GB"
headline	string	yes	—	Editorial weather headline

Usage

## Usage

JSX

import { WeatherBanner } from '@optimists/ui';

Full-width component — span it across all columns. Mood pills are optional but add editorial flavour. Supply up to 3; more than 3 pills will overflow the layout.

DataGrid

2×2 stat grid infographic with emoji badges, large values, and descriptive labels. Use for "key numbers" data panels with exactly 4 stats.

Preview — Default

Navy header with white cells and coloured emoji badges.

BIG DATA — KEY NUMBERS

🏢

90%

Fortune 500 have big data initiatives underway

💼

1.5M

data-savvy jobs needed in the next 5 years

💰

$97K

average annual salary for data analysts in the US

📊

3/4

executives are increasing their use of analytics

Code

JSX

<DataGrid
  title="BIG DATA — KEY NUMBERS"
  cells={[
    { value: '90%', label: 'Fortune 500 have big data initiatives underway', emoji: '🏢' },
    { value: '1.5M', label: 'data-savvy jobs needed in the next 5 years', emoji: '💼' },
    { value: '$97K', label: 'average annual salary for data analysts in the US', emoji: '💰' },
    { value: '3/4', label: 'executives are increasing their use of analytics', emoji: '📊' },
  ]}
/>

Props reference

Props

Prop	Type	Required	Default	Description
title	string	yes	—	Header label, e.g. "BIG DATA — KEY NUMBERS"
cells	[DataGridCell, DataGridCell, DataGridCell, DataGridCell]	yes	—	Exactly 4 cells laid out in row-major 2×2 order
cells[].value	string	yes	—	Large stat value, e.g. "90%"

Usage

## Usage

JSX

import { DataGrid } from '@optimists/ui';

Requires **exactly 4 cells** — the TypeScript type enforces a 4-tuple. Designed at ~400px width. Use standalone or alongside `StatHero` in a full-width data section.

💡

The `cells` prop is typed as a 4-tuple `[DataGridCell, DataGridCell, DataGridCell, DataGridCell]` — TypeScript will error if you pass fewer or more.

StatHero

Full-width hero stat block with a giant display value, unit, context sentence, decorative rings, and an emoji badge. Use as a section opener for data-led stories.

Preview — Sky Blue

Bright sky blue background for a data-positive feel.

DATA & SOCIETY · SPECIAL REPORT

1.5 MILLION

data-savvy managers and analysts

will be needed in the next 5 years to drive decisions globally

Code

JSX

<StatHero
  sectionTag="DATA & SOCIETY  ·  SPECIAL REPORT"
  value="1.5 MILLION"
  unit="data-savvy managers and analysts"
  context="will be needed in the next 5 years to drive decisions globally"
  emoji="📈"
  bgColor="#8CD0ED"
  sectionTagColor="#192A56"
  valueColor="#192A56"
/>

Props reference

Props

Prop	Type	Required	Default	Description
sectionTag	string	yes	—	Overline category label, e.g. "DATA & SOCIETY · SPECIAL REPORT"
value	string	yes	—	Giant hero number/stat, e.g. "1.5 MILLION"
unit	string	yes	—	Unit label below the value

Usage

## Usage

JSX

import { StatHero } from '@optimists/ui';

Full-width component — span across all columns as a section divider. The decorative ring is a subtle background element; `ringColor` adjusts its opacity/colour for contrast. Pair with `DataGrid` or `CardNumberLead` below for a data-forward section.

CardHero

Full-width featured story card with author byline, deck, and optional hero image. Use as the primary headline story on a page or section.

Preview — Climate

Peach background with green climate category chip.

📸 Feature Photo

CLIMATE

6 MIN

The Ocean Cleanup Project Achieves Its Most Ambitious Goal Yet

Three major ocean garbage patches have reduced in size simultaneously for the first time in recorded history.

Sarah OkaforEnvironment Correspondent

Wed 27 May 2026·6 min read

Code

JSX

<CardHero
  headline="The Ocean Cleanup Project Achieves Its Most Ambitious Goal Yet"
  deck="Three major ocean garbage patches have reduced in size simultaneously."
  author="Sarah Okafor"
  role="Environment Correspondent"
  date="Wed 27 May 2026"
  readTime="6 min read"
  category="CLIMATE"
  categoryColor="#C1ECC6"
  categoryTextColor="#0F3B22"
  cardBgColor="#F4C1AE"
/>

Props reference

Props

Prop	Type	Required	Default	Description
headline	string	yes	—	Primary story headline
deck	string	yes	—	Short standfirst / teaser sentence
author	string	yes	—	Author display name

Usage

## Usage

JSX

import { CardHero } from '@optimists/ui';

Place at the top of a news page or section as the featured story. The card auto-generates an avatar initial from the first letter of `author`. Supply `imageSrc` to show a hero image panel on larger screens; omit it for a text-only layout. All colour props are optional overrides — the component ships with sensible navy/white defaults.

💡

The author avatar uses the first character of `author` as its initial. If `imageSrc` is supplied, it displays in a right-side image panel on md+ screens.

FactBoxNavy

Info box with a coloured header panel and a lighter body panel. Use for "did you know?" callouts, glossary definitions, or quick-reference health/science facts.

Preview — Health

Green header with a matching green body panel.

🩺

HEALTH FACT

What is a STROKE?

A stroke occurs when blood flow to part of the brain is cut off — either by a clot (ischemic) or a burst vessel (hemorrhagic). Every second counts.

Source: World Stroke Organisation

Code

JSX

<FactBoxNavy
  label="HEALTH FACT"
  headline="What is a STROKE?"
  body="A stroke occurs when blood flow to part of the brain is cut off."
  source="Source: World Stroke Organisation"
  emoji="🩺"
  headerBgColor="#C1ECC6"
  bodyBgColor="#C1ECC6"
  labelColor="#192A56"
  headlineColor="#192A56"
/>

Props reference

Props

Prop	Type	Required	Default	Description
label	string	yes	—	Uppercase category label, e.g. "HEALTH FACT"
headline	string	yes	—	Bold headline in the header panel
body	string	yes	—	Explanatory body text

Usage

## Usage

JSX

import { FactBoxNavy } from '@optimists/ui';

Use inline within article content or as a sidebar callout. The header and body can be themed independently — a common pattern is to give `headerBgColor` a vivid accent colour and `bodyBgColor` a light tint of the same hue.

PullQuote

Editorial pull quote with a large decorative quotation mark, accent pill, and attribution line. Use between paragraphs to break up long articles.

Preview — Peach

Warm peach background — suits lifestyle and opinion pieces.

The sexy job in the next 10 years will be statisticians. The ability to take data, to understand it, to process it, to extract value from it, to visualise it and communicate it is going to be enormously important.

— Hal Varian, Chief Economist at Google

Code

JSX

<PullQuote
  quote="The sexy job in the next 10 years will be statisticians. The ability to take data, understand it, and communicate it is going to be enormously important."
  attribution="— Hal Varian, Chief Economist at Google"
  bgColor="#F4C1AE"
  quoteColor="#192A56"
  accentColor="#FCE29A"
  attributionColor="#192A56"
/>

Props reference

Props

Prop	Type	Required	Default	Description
quote	string	yes	—	Pull quote text — aim for 100–200 characters for best layout
attribution	string	yes	—	Attribution line — include an em dash, e.g. "— Hal Varian, Chief Economist at Google"
bgColor	string	no	—	Component background override

Usage

## Usage

JSX

import { PullQuote } from '@optimists/ui';

Insert between article paragraphs or at the end of a section. The decorative quote mark fades in opacity based on `decorativeQuoteColor` — passing a semi-transparent value (e.g. `rgba(0,0,0,0.08)`) keeps it subtle. Always include an em dash in `attribution`.

CardNumberLead

Compact accent card led by a large display statistic. Use in grids of 2–3 to surface key numbers alongside a supporting description.

Preview — Community (Sky Blue)

Sky blue background with navy category chip.

3,456

volunteers

COMMUNITY

Joined the coastal clean-up this weekend — a record turnout across 14 counties.

Code

JSX

<CardNumberLead
  number="3,456"
  unit="volunteers"
  description="Joined the coastal clean-up this weekend — a record turnout across 14 counties."
  category="COMMUNITY"
  bgColor="#8CD0ED"
  stripColor="#8CD0ED"
  categoryBgColor="#192A56"
  categoryTextColor="#FFFFFF"
/>

Props reference

Props

Prop	Type	Required	Default	Description
number	string	yes	—	Large display stat, e.g. "3,456" or "94%"
unit	string	yes	—	Label beneath the number, e.g. "volunteers"
description	string	yes	—	Supporting body sentence

Usage

## Usage

JSX

import { CardNumberLead } from '@optimists/ui';

Best displayed in a 2–3 column grid. The large number is the visual anchor — keep `unit` to 2–3 words and `description` to one sentence for maximum impact. Combine with `StatHero` for a data-forward section.

💡

Designed at 220px height. Works best in a `grid-cols-2` or `grid-cols-3` container.

CardListItem

Compact ranked story list card with numbered badges. Use for "top stories" or "most read" sidebars with 3–5 entries.

Preview — Default

Standard list with per-row category chips in different accent colours.

Global Coffee Prices Hit Five-Year Low as Supply Chains Recover

BUSINESS

4h ago

WHO Issues New Treatment Protocol for Faster Stroke Recovery

HEALTH

5h ago

Open-Source AI Model Outperforms Commercial Systems on Key Benchmarks

TECH

6h ago

Code

JSX

<CardListItem
  items={[
    { headline: 'Global Coffee Prices Hit Five-Year Low', time: '4h ago', category: 'BUSINESS', categoryColor: '#FCE29A', categoryTextColor: '#192A56' },
    { headline: 'WHO Issues New Treatment Protocol', time: '5h ago', category: 'HEALTH', categoryColor: '#F4C1AE', categoryTextColor: '#192A56' },
    { headline: 'Open-Source AI Outperforms Commercial Systems', time: '6h ago', category: 'TECH', categoryColor: '#A2CFD0', categoryTextColor: '#192A56' },
  ]}
/>

Props reference

Props

Prop	Type	Required	Default	Description
items	CardListItemRow[]	yes	—	Array of story rows — each has headline, time, and optional category
items[].headline	string	yes	—	Story headline
items[].time	string	yes	—	Relative time label, e.g. "4h ago"

Usage

## Usage

JSX

import { CardListItem } from '@optimists/ui';

Each row renders a rank badge (1, 2, 3…), the headline, a time label, and an optional category chip. Attach `onItemClick` to navigate to the story on row click.

💡

The component renders as many rows as supplied in `items` — no upper limit enforced, but 3–5 rows work best visually.

CardBrief

Compact 220px brief card with no image, carrying headline, teaser, time, and an optional read-more link. Use in tight multi-column news grids.

Preview — World (Periwinkle)

Light blue background with periwinkle category accent.

WORLD

1h ago

UN Climate Summit Reaches Historic Fossil Fuel Phase-Out Agreement

140 countries sign a landmark accord to phase out coal by 2040 — the most ambitious commitment yet.

→ Read more

Code

JSX

<CardBrief
  headline="UN Climate Summit Reaches Historic Fossil Fuel Phase-Out Agreement"
  description="140 countries sign a landmark accord to phase out coal by 2040."
  time="1h ago"
  category="WORLD"
  accentColor="#B9C7FF"
  categoryTextColor="#192A56"
  bgColor="#EDF1FF"
/>

Props reference

Props

Prop	Type	Required	Default	Description
headline	string	yes	—	Story headline
description	string	yes	—	Short teaser sentence
time	string	yes	—	Relative or absolute time label, e.g. "1h ago"

Usage

## Usage

JSX

import { CardBrief } from '@optimists/ui';

Use in a 3-column grid alongside `CardFeature` or `CardHero` to fill secondary story slots. The card is fixed at ~220px height, so keep headline and description concise. Supply `readMore` to show a bottom CTA link with a divider rule.

💡

Designed at 220px height — pair with CardNumberLead in the same row for visual variety.

optimists — Component Library

Component Docs

Live previews, prop tables, and usage guides for every component in the @optimists/ui package. Figma design file: LmuR42ZKVVmfysQRtJXQAb

View Demo →13 components

Available on npm

Use these components to share some positive news.

@optimists/ui is an open-source React component library built for publishers who want to surface good-news stories with clarity and style.

Install

npm i @optimists/ui

Quick start

JSX

import { CardHero, StatHero, PullQuote } from '@optimists/ui';

export default function NewsPage() {
  return (
    <CardHero
      headline="Scientists discover ocean cleans itself faster than thought"
      deck="New research shows micro-organisms breaking down plastic at record rates."
      sectionTag="Environment"
      readTime="3 min read"
    />
  );
}

View on npmjs.com ↗

Components

13 components — live previews, props, and usage guides.

CardFeature

Half-page 360px story card with an optional image area, author metadata, and a category accent strip. Use for secondary feature stories in a 2–3 column grid.

Preview — Science

Teal accent with default white background.

📸 Photo

SCIENCE

Mon 25 May

4 min read

New Research Confirms Why Your Coffee Actually Makes You More Productive

MIT researchers have pinpointed the exact neural pathway caffeine activates to boost sustained concentration.

Marcus Chen

Code

JSX

<CardFeature
  headline="New Research Confirms Why Your Coffee Actually Makes You More Productive"
  description="MIT researchers have pinpointed the neural pathway caffeine activates."
  author="Marcus Chen"
  date="Mon 25 May"
  readTime="4 min read"
  category="SCIENCE"
  accentColor="#A2CFD0"
  categoryTextColor="#192A56"
/>

Props reference

Props

Prop	Type	Required	Default	Description
headline	string	yes	—	Story headline
description	string	yes	—	Short standfirst / teaser
author	string	yes	—	Author display name

Usage

## Usage

JSX

import { CardFeature } from '@optimists/ui';

💡

Designed at approximately 360px height. The author avatar uses the first character of `author`.

RankList

Top-5 ranked infographic list with flag/icon emoji, item labels, and value pills. Use for "best of" rankings, league tables, or fact-check comparisons.

Preview — Happiness Index

Green header with alternating teal row stripes.

TOP 5 HAPPIEST COUNTRIES

World Happiness Report 2024 ranking

🇫🇮

Finland

7.74

🇩🇰

Denmark

7.58

🇮🇸

Iceland

7.53

🇸🇪

Sweden

7.34

🇮🇱

Israel

7.34

Source: UN World Happiness Report, 2024

Code

JSX

<RankList
  title="TOP 5 HAPPIEST COUNTRIES"
  subtitle="World Happiness Report 2024 ranking"
  entries={[
    { flag: '🇫🇮', item: 'Finland', value: '7.74' },
    { flag: '🇩🇰', item: 'Denmark', value: '7.58' },
    { flag: '🇮🇸', item: 'Iceland', value: '7.53' },
    { flag: '🇸🇪', item: 'Sweden', value: '7.34' },
    { flag: '🇮🇱', item: 'Israel', value: '7.34' },
  ]}
  source="Source: UN World Happiness Report, 2024"
  headerBgColor="#153B2E"
  titleColor="#C1ECC6"
/>

Props reference

Props

Prop	Type	Required	Default	Description
title	string	yes	—	Header label, e.g. "TOP 5 COFFEE PRODUCERS"
subtitle	string	yes	—	Subheading beneath the title
entries	RankListEntry[]	yes	—	Ranked rows — each has flag, item, and value

Usage

## Usage

JSX

import { RankList } from '@optimists/ui';

Timeline

Vertical 4-entry timeline infographic with year badges, event titles, and detail sentences. Use for historical context panels or process flows.

Preview — Internet History

Default styling — grey header, alternating white rows.

THE INTERNET — A TIMELINE

1969

ARPANET goes online

The first message is sent between UCLA and Stanford University

1991

World Wide Web is born

Tim Berners-Lee creates HTML and launches the first website

2004

Social media era begins

Facebook launches, permanently changing how billions of people connect

2023

AI reshapes the web

Large language models transform search, content and creative work forever

Source: Computer History Museum, 2024

Code

JSX

<Timeline
  title="THE INTERNET — A TIMELINE"
  entries={[
    { year: '1969', event: 'ARPANET goes online', detail: 'First message sent between UCLA and Stanford' },
    { year: '1991', event: 'World Wide Web is born', detail: 'Tim Berners-Lee creates HTML' },
    { year: '2004', event: 'Social media era begins', detail: 'Facebook launches' },
    { year: '2023', event: 'AI reshapes the web', detail: 'Large language models transform creative work' },
  ]}
  source="Source: Computer History Museum, 2024"
/>

Props reference

Props

Prop	Type	Required	Default	Description
title	string	yes	—	Header label, e.g. "THE INTERNET — A TIMELINE"
entries	TimelineEntry[]	yes	—	Timeline rows — each has year, event, detail, and optional badge colour
entries[].year	string	yes	—	Year or era label shown in the circular badge

Usage

## Usage

JSX

import { Timeline } from '@optimists/ui';

Designed to be ~360px wide — works well beside `RankList` in a 2–3 column infographic row. Per-entry `badgeColor` lets you colour-code entries (e.g. green for milestones, yellow for key events).

CompareBlock

Full-width side-by-side A vs B comparison card with large stats, descriptions, and icon badges. Use for fact-check or "did you know?" infographic comparisons.

Preview — Medical

Default navy header with white columns.

ISCHEMIC STROKE

HEMORRHAGIC STROKE

🧠

87%

of all strokes are ischemic

Occurs when arteries are blocked by blood clots or gradual build-up of plaque. Most common — and most treatable.

🩸

13%

of strokes, yet 30%+ of deaths

Occurs when a blood vessel breaks. Less common than ischemic but far more likely to be fatal.

Code

JSX

<CompareBlock
  labelA="ISCHEMIC STROKE"
  labelB="HEMORRHAGIC STROKE"
  statA="87%"
  statALabel="of all strokes are ischemic"
  descA="Occurs when arteries are blocked by blood clots or gradual build-up of plaque."
  statB="13%"
  statBLabel="of strokes, yet 30%+ of deaths"
  descB="Occurs when a blood vessel breaks."
  emojiA="🧠"
  emojiB="🩸"
/>

Props reference

Props

Prop	Type	Required	Default	Description
labelA	string	yes	—	Left column header label, e.g. "ISCHEMIC STROKE"
labelB	string	yes	—	Right column header label
statA	string	yes	—	Large stat value for the left column, e.g. "87%"

Usage

## Usage

JSX

import { CompareBlock } from '@optimists/ui';

Full-width component designed at ~746px. Use it once per section — not in a grid. Supply emoji badges (`emojiA`, `emojiB`) to add visual anchors; omit them for a cleaner text-only layout.

WeatherBanner

Full-width editorial weather banner with a large emoji, location, headline, prose, and up to 3 mood pills. Use as a contextual header for weather or wellbeing stories.

Preview — Sunny

Yellow background for bright sunny weather.

☀️

WEATHER

Near Edinburgh, GB

Sunshine and highs of 12°c in sunny Scotland today.

The people and plants are going to be very happy. A glorious day ahead — expect smiles, open windows, and maybe a spontaneous walk.

🌿Plants happy

😊People smiling

🪟Windows open

Code

JSX

<WeatherBanner
  mainEmoji="☀️"
  location="Near Edinburgh, GB"
  headline="Sunshine and highs of 12°c in sunny Scotland today."
  prose="A glorious day ahead — expect smiles and open windows."
  moodPills={[
    { emoji: '🌿', label: 'Plants happy' },
    { emoji: '😊', label: 'People smiling' },
    { emoji: '🪟', label: 'Windows open' },
  ]}
  bgColor="#fce29a"
  categoryBgColor="#192a56"
/>

Props reference

Props

Prop	Type	Required	Default	Description
mainEmoji	string	yes	—	Large weather emoji in the left column, e.g. "☀️"
location	string	yes	—	Location label, e.g. "Near Edinburgh, GB"
headline	string	yes	—	Editorial weather headline

Usage

## Usage

JSX

import { WeatherBanner } from '@optimists/ui';

Full-width component — span it across all columns. Mood pills are optional but add editorial flavour. Supply up to 3; more than 3 pills will overflow the layout.

DataGrid

2×2 stat grid infographic with emoji badges, large values, and descriptive labels. Use for "key numbers" data panels with exactly 4 stats.

Preview — Default

Navy header with white cells and coloured emoji badges.

BIG DATA — KEY NUMBERS

🏢

90%

Fortune 500 have big data initiatives underway

💼

1.5M

data-savvy jobs needed in the next 5 years

💰

$97K

average annual salary for data analysts in the US

📊

3/4

executives are increasing their use of analytics

Code

JSX

<DataGrid
  title="BIG DATA — KEY NUMBERS"
  cells={[
    { value: '90%', label: 'Fortune 500 have big data initiatives underway', emoji: '🏢' },
    { value: '1.5M', label: 'data-savvy jobs needed in the next 5 years', emoji: '💼' },
    { value: '$97K', label: 'average annual salary for data analysts in the US', emoji: '💰' },
    { value: '3/4', label: 'executives are increasing their use of analytics', emoji: '📊' },
  ]}
/>

Props reference

Props

Prop	Type	Required	Default	Description
title	string	yes	—	Header label, e.g. "BIG DATA — KEY NUMBERS"
cells	[DataGridCell, DataGridCell, DataGridCell, DataGridCell]	yes	—	Exactly 4 cells laid out in row-major 2×2 order
cells[].value	string	yes	—	Large stat value, e.g. "90%"

Usage

## Usage

JSX

import { DataGrid } from '@optimists/ui';

Requires **exactly 4 cells** — the TypeScript type enforces a 4-tuple. Designed at ~400px width. Use standalone or alongside `StatHero` in a full-width data section.

💡

The `cells` prop is typed as a 4-tuple `[DataGridCell, DataGridCell, DataGridCell, DataGridCell]` — TypeScript will error if you pass fewer or more.

StatHero

Full-width hero stat block with a giant display value, unit, context sentence, decorative rings, and an emoji badge. Use as a section opener for data-led stories.

Preview — Sky Blue

Bright sky blue background for a data-positive feel.

DATA & SOCIETY · SPECIAL REPORT

1.5 MILLION

data-savvy managers and analysts

will be needed in the next 5 years to drive decisions globally

Code

JSX

<StatHero
  sectionTag="DATA & SOCIETY  ·  SPECIAL REPORT"
  value="1.5 MILLION"
  unit="data-savvy managers and analysts"
  context="will be needed in the next 5 years to drive decisions globally"
  emoji="📈"
  bgColor="#8CD0ED"
  sectionTagColor="#192A56"
  valueColor="#192A56"
/>

Props reference

Props

Prop	Type	Required	Default	Description
sectionTag	string	yes	—	Overline category label, e.g. "DATA & SOCIETY · SPECIAL REPORT"
value	string	yes	—	Giant hero number/stat, e.g. "1.5 MILLION"
unit	string	yes	—	Unit label below the value

Usage

## Usage

JSX

import { StatHero } from '@optimists/ui';

CardHero

Full-width featured story card with author byline, deck, and optional hero image. Use as the primary headline story on a page or section.

Preview — Climate

Peach background with green climate category chip.

📸 Feature Photo

CLIMATE

6 MIN

The Ocean Cleanup Project Achieves Its Most Ambitious Goal Yet

Three major ocean garbage patches have reduced in size simultaneously for the first time in recorded history.

Sarah OkaforEnvironment Correspondent

Wed 27 May 2026·6 min read

Code

JSX

<CardHero
  headline="The Ocean Cleanup Project Achieves Its Most Ambitious Goal Yet"
  deck="Three major ocean garbage patches have reduced in size simultaneously."
  author="Sarah Okafor"
  role="Environment Correspondent"
  date="Wed 27 May 2026"
  readTime="6 min read"
  category="CLIMATE"
  categoryColor="#C1ECC6"
  categoryTextColor="#0F3B22"
  cardBgColor="#F4C1AE"
/>

Props reference

Props

Prop	Type	Required	Default	Description
headline	string	yes	—	Primary story headline
deck	string	yes	—	Short standfirst / teaser sentence
author	string	yes	—	Author display name

Usage

## Usage

JSX

import { CardHero } from '@optimists/ui';

💡

The author avatar uses the first character of `author` as its initial. If `imageSrc` is supplied, it displays in a right-side image panel on md+ screens.

FactBoxNavy

Info box with a coloured header panel and a lighter body panel. Use for "did you know?" callouts, glossary definitions, or quick-reference health/science facts.

Preview — Health

Green header with a matching green body panel.

🩺

HEALTH FACT

What is a STROKE?

A stroke occurs when blood flow to part of the brain is cut off — either by a clot (ischemic) or a burst vessel (hemorrhagic). Every second counts.

Source: World Stroke Organisation

Code

JSX

<FactBoxNavy
  label="HEALTH FACT"
  headline="What is a STROKE?"
  body="A stroke occurs when blood flow to part of the brain is cut off."
  source="Source: World Stroke Organisation"
  emoji="🩺"
  headerBgColor="#C1ECC6"
  bodyBgColor="#C1ECC6"
  labelColor="#192A56"
  headlineColor="#192A56"
/>

Props reference

Props

Prop	Type	Required	Default	Description
label	string	yes	—	Uppercase category label, e.g. "HEALTH FACT"
headline	string	yes	—	Bold headline in the header panel
body	string	yes	—	Explanatory body text

Usage

## Usage

JSX

import { FactBoxNavy } from '@optimists/ui';

PullQuote

Editorial pull quote with a large decorative quotation mark, accent pill, and attribution line. Use between paragraphs to break up long articles.

Preview — Peach

Warm peach background — suits lifestyle and opinion pieces.

— Hal Varian, Chief Economist at Google

Code

JSX

<PullQuote
  quote="The sexy job in the next 10 years will be statisticians. The ability to take data, understand it, and communicate it is going to be enormously important."
  attribution="— Hal Varian, Chief Economist at Google"
  bgColor="#F4C1AE"
  quoteColor="#192A56"
  accentColor="#FCE29A"
  attributionColor="#192A56"
/>

Props reference

Props

Prop	Type	Required	Default	Description
quote	string	yes	—	Pull quote text — aim for 100–200 characters for best layout
attribution	string	yes	—	Attribution line — include an em dash, e.g. "— Hal Varian, Chief Economist at Google"
bgColor	string	no	—	Component background override

Usage

## Usage

JSX

import { PullQuote } from '@optimists/ui';

CardNumberLead

Compact accent card led by a large display statistic. Use in grids of 2–3 to surface key numbers alongside a supporting description.

Preview — Community (Sky Blue)

Sky blue background with navy category chip.

3,456

volunteers

COMMUNITY

Joined the coastal clean-up this weekend — a record turnout across 14 counties.

Code

JSX

<CardNumberLead
  number="3,456"
  unit="volunteers"
  description="Joined the coastal clean-up this weekend — a record turnout across 14 counties."
  category="COMMUNITY"
  bgColor="#8CD0ED"
  stripColor="#8CD0ED"
  categoryBgColor="#192A56"
  categoryTextColor="#FFFFFF"
/>

Props reference

Props

Prop	Type	Required	Default	Description
number	string	yes	—	Large display stat, e.g. "3,456" or "94%"
unit	string	yes	—	Label beneath the number, e.g. "volunteers"
description	string	yes	—	Supporting body sentence

Usage

## Usage

JSX

import { CardNumberLead } from '@optimists/ui';

💡

Designed at 220px height. Works best in a `grid-cols-2` or `grid-cols-3` container.

CardListItem

Compact ranked story list card with numbered badges. Use for "top stories" or "most read" sidebars with 3–5 entries.

Preview — Default

Standard list with per-row category chips in different accent colours.

Global Coffee Prices Hit Five-Year Low as Supply Chains Recover

BUSINESS

4h ago

WHO Issues New Treatment Protocol for Faster Stroke Recovery

HEALTH

5h ago

Open-Source AI Model Outperforms Commercial Systems on Key Benchmarks

TECH

6h ago

Code

JSX

<CardListItem
  items={[
    { headline: 'Global Coffee Prices Hit Five-Year Low', time: '4h ago', category: 'BUSINESS', categoryColor: '#FCE29A', categoryTextColor: '#192A56' },
    { headline: 'WHO Issues New Treatment Protocol', time: '5h ago', category: 'HEALTH', categoryColor: '#F4C1AE', categoryTextColor: '#192A56' },
    { headline: 'Open-Source AI Outperforms Commercial Systems', time: '6h ago', category: 'TECH', categoryColor: '#A2CFD0', categoryTextColor: '#192A56' },
  ]}
/>

Props reference

Props

Prop	Type	Required	Default	Description
items	CardListItemRow[]	yes	—	Array of story rows — each has headline, time, and optional category
items[].headline	string	yes	—	Story headline
items[].time	string	yes	—	Relative time label, e.g. "4h ago"

Usage

## Usage

JSX

import { CardListItem } from '@optimists/ui';

Each row renders a rank badge (1, 2, 3…), the headline, a time label, and an optional category chip. Attach `onItemClick` to navigate to the story on row click.

💡

The component renders as many rows as supplied in `items` — no upper limit enforced, but 3–5 rows work best visually.

CardBrief

Compact 220px brief card with no image, carrying headline, teaser, time, and an optional read-more link. Use in tight multi-column news grids.

Preview — World (Periwinkle)

Light blue background with periwinkle category accent.

WORLD

1h ago

UN Climate Summit Reaches Historic Fossil Fuel Phase-Out Agreement

140 countries sign a landmark accord to phase out coal by 2040 — the most ambitious commitment yet.

→ Read more

Code

JSX

<CardBrief
  headline="UN Climate Summit Reaches Historic Fossil Fuel Phase-Out Agreement"
  description="140 countries sign a landmark accord to phase out coal by 2040."
  time="1h ago"
  category="WORLD"
  accentColor="#B9C7FF"
  categoryTextColor="#192A56"
  bgColor="#EDF1FF"
/>

Props reference

Props

Prop	Type	Required	Default	Description
headline	string	yes	—	Story headline
description	string	yes	—	Short teaser sentence
time	string	yes	—	Relative or absolute time label, e.g. "1h ago"

Usage

## Usage

JSX

import { CardBrief } from '@optimists/ui';

💡

Designed at 220px height — pair with CardNumberLead in the same row for visual variety.