Data Display

FeedEvent

Individual entry within a feed that pairs a timestamp with a content snippet and optional leading icon.

import { FeedEvent } from '@lostgradient/cinder/feed-event';
timelineevent
01

Overview

Individual timestamped entry within a chronological activity feed.

Usage

FeedEvent is a compose-only leaf of Feed. The idiomatic API is Feed.Event, reached through the parent namespace — see the feed README for the composed snippet. The flat @lostgradient/cinder/feed-event subpath remains exported for à-la-carte builds that import the leaf directly.

02

When to use

Use when
  • Rendering a single activity or audit entry inside a feed parent.
  • Switching between an icon-led and a connector-led visual treatment via the variant prop.
Avoid when
  • Standing alone outside a feed — it expects the feed list semantics around it.
03

Props

Props for feed-event
Name Type Default Required Bindable Description
datetime text req ISO 8601 datetime string. Rendered as <time datetime={datetime}> so assistive tech and parsers receive a machine-readable timestamp. This is always the authoritative value; the visible label is separate (see timestamp / timestampLabel).
variant discriminated-union 'icon' Icon variant: renders a circular badge on the rail with the icon inside.
icon discriminated-union Required for the icon variant. Type-enforced by the discriminated union.
children snippet Main event body — the description, links, and secondary metadata. Passed as the default children snippet: ``svelte <FeedEvent datetime="…" timestamp="2m ago"> <strong>{user.name}</strong> pushed 3 commits </FeedEvent> ``
timestamp text Visible time label, as plain text — the common case ("2m ago", "May 12, 3:30 PM"). Rendered inside the <time> element. Optional, with a deliberate three-way contract: - omitted (undefined) and no timestampLabel → falls back to the raw datetime string, which is deterministic and SSR-safe (no locale or timezone dependence). - explicit empty string (timestamp="") → renders no visible label. This is treated as "intentionally blank", NOT as omitted, so it does not trigger the datetime fallback. Use it to hide the label while keeping the machine-readable <time datetime> for assistive tech. - non-empty string → rendered verbatim.
timestampLabel snippet Rich visible time label, for the rare case where the label needs markup (e.g. an <abbr> or nested element). Takes precedence over timestamp when both are supplied. Most consumers should use the timestamp string instead.