Stat
A single KPI: a muted label over a large metric value.
Installation
Included in poetry-ui — available as
poetry_stat
the moment you've installed Poetry,
with no per-component step. To own the source and edit it, copy it into your app:
bin/rails g poetry:add stat
Default
Open Default standalone
Revenue
$45,231
+20.1%trending up
Churn
2.1%
-0.8%trending down
Uptime
99.98%
0.00%flat
<div class="grid w-full max-w-2xl gap-6 sm:grid-cols-3">
<%= poetry_stat(label: "Revenue", delta: "+20.1%", trend: :up) { "$45,231" } %>
<%= poetry_stat(label: "Churn", delta: "-0.8%", trend: :down, sentiment: :positive) { "2.1%" } %>
<%= poetry_stat(label: "Uptime", delta: "0.00%", trend: :flat) { "99.98%" } %>
</div>
With description
Open With description standalone
Open invoices
38
+4trending up
12 overdue past 30 days
<%= poetry_stat(label: "Open invoices", delta: "+4", trend: :up, sentiment: :negative) do |stat| %>
<% stat.with_description { "12 overdue past 30 days" } %>
38
<% end %>
API
Poetry::Ui::Stat::Component — options are
constructor keywords (the poetry_* helper forwards them);
slots are composed inside the block. Generated from the gem's source documentation.
| Option | Type | Details | Description |
|---|---|---|---|
| delta: | String | The change text shown in the pill beside the value (\"+12.5%\"). | |
| label: | String | required | The metric's name, shown muted above the value. |
| sentiment: | Symbol | one of: positive, negative, neutral; |
Overrides the trend-derived sentiment - color follows sentiment, never the arrow (set :positive when DOWN is the good direction). |
| trend: | Symbol | one of: up, down, flat; defaults to :up |
The arrow direction; also derives the default sentiment. |
Slots
| Writer | Description |
|---|---|
| with_description | Muted supporting copy rendered under the value. |
| with_media | The trend-visual slot (sparkline, chart, glyph) below the text stack. |
Styling
Every part carries a stable data-slot attribute — target
[data-slot=…] from your own CSS to restyle it. State rides
data attributes on the parts below. This contract is verified against rendered DOM in CI.
| Part | Description |
|---|---|
| [data-slot=stat] | The stat root - a label/value/delta/description column |
| [data-slot=stat-label] | The muted metric name above the value |
| [data-slot=stat-value] | The metric itself - large, semibold, tabular numerals |
| [data-slot=stat-delta] | The change pill beside the value - arrow icon + delta text with an sr-only trend word |
| [data-slot=stat-description] | Muted supporting copy under the value |
| [data-slot=stat-media] | The trend-visual slot (sparkline, chart, glyph) below the text stack |
State attributes
| Part | Attribute | Condition | Values |
|---|---|---|---|
| stat-delta | data-trend | always - the arrow direction | up · down · flat |
| stat-delta | data-sentiment | always - resolved sentiment (trend-derived unless overridden) | positive · negative · neutral |