gnome-ui¶
A React component library that faithfully implements the GNOME Human Interface Guidelines, built on top of the Adwaita design language.
Read the guides, architecture, design guidelines, roadmap, and changelog at gnome-ui.org — and browse every component live, with real interactive previews, in each package's own Storybook (linked throughout, and per-row in the tables below).
Packages¶
| Package | Description | Version |
|---|---|---|
@gnome-ui/core |
Framework-agnostic design tokens (CSS custom properties) |  |
@gnome-ui/icons |
Framework-agnostic Adwaita symbolic icon definitions (SVG path data) |  |
@gnome-ui/react |
React component library | |
@gnome-ui/layout |
Full-page application shell and dashboard components |  |
@gnome-ui/platform |
TypeScript bridge to GNOME host APIs (GSettings, portals, notifications…) |  |
@gnome-ui/hooks |
React hooks that surface @gnome-ui/platform APIs as idiomatic React state |
 |
@gnome-ui/charts |
Data visualisation components (Line, Bar, Area) styled with Adwaita tokens |  |
@gnome-ui/react-native |
React Native components for iOS/Android/GNOME-mobile |  |
Quick start¶
import { Button } from "@gnome-ui/react";
import "@gnome-ui/react/styles";
export default function App() {
return (
<Button variant="suggested" onClick={() => console.log("clicked")}>
Save Changes
</Button>
);
}
Locale & number formatting¶
Wrap your app in GnomeProvider to share locale, text direction, and default Intl options across @gnome-ui/react, @gnome-ui/layout, and @gnome-ui/charts.
import { GnomeProvider } from "@gnome-ui/react";
<GnomeProvider
locale="en-US"
numberFormat={{ notation: "compact", compactDisplay: "short" }}
>
<App />
</GnomeProvider>
Compact notation renders values like 1K; standard notation renders values like 1,000.
Tokens only (framework-agnostic):
Components¶
Live examples and documentation: Storybook →
AI assistants and coding agents can use llms.txt
for a compact documentation index or
llms-full.txt for complete context.
The React Native and Web Components columns show each component's
port status in @gnome-ui/react-native
and @gnome-ui/web-components:
✅ shipped · 🚧 in progress · ⬜ planned · 🚫 not planned · — not tracked
there (see that package's own ROADMAP.md for why — usually a
domain-specific or React-only component with no cross-platform target).
Generated by scripts/generate-component-tables.mjs
from those two files — edit them, not this table, then run
npm run tables:generate.
| Component | Description | React Native | Web Components | Story |
|---|---|---|---|---|
AboutDialog |
Standard app info dialog with details, credits, and legal tabs. Mirrors AdwAboutDialog. |
🚫 | — | Docs |
ActionRow |
Standard settings row with title, optional subtitle, leading icon, and trailing widget. | ✅ | ✅ | Docs |
AffectedPackage |
— | — | Docs | |
AnimatedIcon |
Plays the CSS animation embedded in an animated icon from @gnome-ui/icons — Syncing, Recording, Downloading, Connecting. Rendered through plain Icon instead, these show a static frame; AnimatedIcon is what turns the animation on. |
✅ | — | Docs |
Avatar |
Circular avatar following the Adwaita AdwAvatar pattern. |
✅ | ✅ | Docs |
AvatarGroup |
Stack of avatars with overflow indicator. | ✅ | — | Docs |
AvatarRotator |
Single avatar surface that crossfades through multiple image sources. | ✅ | — | Docs |
Badge |
Counter or status indicator, optionally overlaid on another element. | ✅ | ✅ | Docs |
Banner |
Persistent message strip displayed at the top of a view. | ✅ | ✅ | Docs |
Bin |
Single-child container with no visual styling. | ✅ | ✅ | Docs |
Blockquote |
Styled pull-quote with semantic <blockquote> markup. |
✅ | — | Docs |
BottomSheet |
Slide-up panel that overlays content from the bottom edge. | ✅ | — | Docs |
BoxedList |
Rounded bordered list — the most common container pattern in GNOME settings and detail views. | ✅ | ✅ | Docs |
BreakpointBin |
Container that fires layout changes when its own width crosses defined thresholds — the CSS container-query equivalent of AdwBreakpointBin (libadwaita 1.9 / GNOME 50). |
✅ | — | Docs |
Button |
Button component following the GNOME Human Interface Guidelines. | ✅ | ✅ | Docs |
ButtonContent |
Icon + label layout helper for buttons that contain both an icon and text. | ✅ | — | Docs |
ButtonRow |
Full-width activatable row styled as a button inside a BoxedList. |
✅ | — | Docs |
Calendar |
Month-grid date display with full keyboard navigation — mirrors GtkCalendar. Usable standalone (settings, forms) or as the panel inside a DatePicker. |
⬜ | — | Docs |
CalendarRange |
Start/end date-range selection driving the same grid engine as Calendar — roving tabindex, month/year drill-down, min/max, week numbers, localisation. |
⬜ | — | Docs |
Callout |
Inline, dismissible admonition box for contextual help text within forms and cards. | ✅ | ✅ | Docs |
Card |
Card component following the GNOME HIG containers and the Adwaita .card style class. |
✅ | ✅ | Docs |
Carousel |
Swipeable content carousel. | ⬜ | — | Docs |
Checkbox |
Checkbox for multi-selection, following the GNOME HIG and Adwaita style. | ✅ | ✅ | Docs |
CheckRow |
Activatable row with an integrated checkbox. | ✅ | — | Docs |
Chip |
Compact pill-shaped label for tags, filters, and selection states. | ✅ | ⬜ | Docs |
ChoiceCardGroup |
Card-based single-choice selector — large selectable cards instead of radio buttons. | ⬜ | ✅ | Docs |
Clamp |
Constrains its child to a maximum width while allowing it to shrink freely on narrow screens — mirroring the Adwaita AdwClamp widget. |
✅ | — | Docs |
CoachMark |
Onboarding feature-discovery pattern: spotlight a UI element and anchor a callout bubble (title, description, actions) beside it to teach a user one feature. Compose several with CoachMarkTour, or drive a single mark with open. |
✅ | — | Docs |
CodeBlock |
Static monospace code/config snippet display with optional line numbers and a trailing CopyButton. |
⬜ | ⬜ | Docs |
ColorPicker |
Color palette picker following the Adwaita GtkColorButton + swatch pattern. |
✅ | — | Docs |
ColumnView |
Multi-column sortable data table styled with Adwaita design tokens. | 🚫 | — | Docs |
ComboRow |
Settings row with an inline combo selector at the trailing edge. | ✅ | ✅ | Docs |
ContributionGraph |
A responsive activity heatmap calendar styled with Adwaita design tokens. Colour intensity represents activity count per day. | 🚫 | — | Docs |
CopyButton |
Icon button that copies a value to the clipboard, swapping to a checkmark and a "Copied!" tooltip as confirmation. | ✅ | ✅ | Docs |
CopyField |
Read-only TextField with a built-in trailing CopyButton, for displaying copyable values (API keys, tokens, IDs) outside the CveIdentifier/CweIdentifier-style specialised components. |
⬜ | ⬜ | Docs |
CountDownTimer |
Displays a countdown timer showing the remaining time until a specified end date. | ⬜ | — | Docs |
CveIdentifier |
Monospace CVE identifier for vulnerability tables, findings, and report references. | — | — | Docs |
CvssScore |
Compact CVSS score display for vulnerability tables, finding summaries, and CVE detail surfaces. | — | — | Docs |
CvssVector |
— | — | Docs | |
CweIdentifier |
— | — | Docs | |
DatePicker |
A Popover-anchored Calendar behind an entry-styled trigger — mirrors the GtkCalendar + GtkPopover composition GNOME apps use for date entry. |
⬜ | — | Docs |
DateRangePicker |
A Popover-anchored CalendarRange behind an entry-styled trigger — the range counterpart of DatePicker, and the same GtkCalendar + GtkPopover composition GNOME apps use for date entry. |
⬜ | — | Docs |
Dialog |
Blocking modal dialog — two modes in one component. | ✅ | ✅ | Docs |
Divider |
Horizontal rule with an optional centred label — common auth/login-form pattern. | ✅ | ✅ | Docs |
Drawer |
Slide-over panel for supplementary React content. Use side to open from the left or right, size for classic or wide widths, and pass the body through children or the content prop. |
✅ | — | Docs |
Dropdown |
Expandable option list following the Adwaita combo-row / drop-down style. | ✅ | ✅ | Docs |
EmojiPicker |
Searchable emoji grid in a Popover. Mirrors GtkEmojiChooser. |
⬜ | ⬜ | Docs |
EntryRow |
Row with an inline text entry field. | ✅ | — | Docs |
Expander |
Standalone disclosure triangle + collapsible content — mirrors GtkExpander. |
✅ | ✅ | Docs |
ExpanderRow |
Collapsible ActionRow that reveals nested rows on activation. |
✅ | ✅ | Docs |
FieldGroup |
Generic form-field grouping with a shared label, help text, and error message, for arbitrary fields outside a BoxedList. |
✅ | ✅ | Docs |
FileDropZone |
Drag-and-drop file upload target with hover/active states, falling back to a GtkFileDialog-style click-to-browse trigger. |
⬜ | ✅ | Docs |
FileTypeIcon |
Small icon — optionally a thumbnail — resolved from a file's MIME type or name extension. Useful for file-manager-style listings. | ✅ | ✅ | Docs |
FilterableMultiSelectDropdown |
MultiSelectDropdown plus a filter field for narrowing long option lists. |
— | — | Docs |
FontPicker |
Button that opens a family/size/weight chooser. Mirrors GtkFontDialogButton: the trigger itself previews the current selection rendered in that font. |
⬜ | ⬜ | Docs |
Footer |
Bottom bar with leading/trailing slots and optional center content. | ⬜ | — | Docs |
Frame |
Simple bordered surface with border-radius but no background fill. |
⬜ | — | Docs |
HeaderBar |
Title bar with centered title and leading/trailing action slots. | ✅ | ✅ | Docs |
Highlight |
Wraps every occurrence of query within text in a <mark> element. |
✅ | ✅ | Docs |
Icon |
Renders an @gnome-ui/icons definition as an inline SVG. |
✅ | — | Docs |
IconButton |
Icon-only action button composed from Button, Icon, and optionally Tooltip. |
✅ | ✅ | Docs |
InlineViewSwitcher |
Compact inline view switcher for placing inside content areas, cards, or toolbars. | ✅ | — | Docs |
Kbd |
Standalone single key-cap for inline instructional text. | 🚫 | ✅ | Docs |
LevelBar |
Discrete level indicator with colour-coded low/high offset zones — mirrors GtkLevelBar. |
✅ | ✅ | Docs |
Link |
Inline hyperlink following GNOME HIG. | ✅ | — | Docs |
LinkedGroup |
Renders children as a single visually-connected unit with no gap and merged borders. | ✅ | ✅ | Docs |
Modal |
— | — | Docs | |
MultiSelectDropdown |
Checkbox-list variant of Dropdown for selecting multiple values from a single trigger. |
✅ | ⬜ | Docs |
NavigationSplitView |
Two-pane sidebar + content layout that collapses to a single navigable pane on narrow screens (≤ 400 px), mirroring AdwNavigationSplitView. |
✅ | — | Docs |
NavigationView |
Single-pane push/pop navigation stack. | ⬜ | — | Docs |
OtpInput |
Segmented PIN/verification-code input — one cell per digit, with auto-advance on typing, backspace-to-previous-cell, and paste support. | ⬜ | ✅ | Docs |
Overlay |
Standalone backdrop/scrim layer with a fade transition and click-to-dismiss — the shared building block behind Modal, Dialog, and BottomSheet's backdrops, extracted for building custom overlay UI. |
✅ | ⬜ | Docs |
OverlaySplitView |
Sidebar + content layout where the sidebar becomes a slide-over overlay on narrow screens (≤ 400 px), mirroring AdwOverlaySplitView. |
⬜ | — | Docs |
PasswordEntryRow |
Password entry row with a built-in reveal/conceal toggle. | ✅ | — | Docs |
PasswordField |
Single-line password input with a peek toggle that reveals the value as plain text. | ✅ | ⬜ | Docs |
PathBar |
Breadcrumb path bar for navigating a hierarchical location. | ✅ | — | Docs |
Popover |
Floating panel anchored to a trigger element, following the Adwaita GtkPopover pattern. |
✅ | ✅ | Docs |
Portal |
Reusable createPortal wrapper — SSR-safe (renders children inline when document is unavailable) with optional mount-target support. |
🚫 | — | Docs |
PreferencesDialog |
Multi-page settings dialog using PreferencesPage tabs. |
⬜ | — | Docs |
PreferencesGroup |
Titled section that wraps a BoxedList with an optional description. |
✅ | — | Docs |
PreferencesPage |
Scrollable page composed of PreferencesGroup sections. |
⬜ | — | Docs |
ProgressBar |
Determinate and indeterminate progress bar following the Adwaita style. | ✅ | ✅ | Docs |
RadioButton |
Single-selection radio button following the GNOME HIG and Adwaita style. | ✅ | ✅ | Docs |
RangeSlider |
Dual-thumb slider for selecting a min/max range, following the Adwaita GtkScale pattern used by Slider. |
✅ | ⬜ | Docs |
RatingStars |
Star rating display and input. | ✅ | ✅ | Docs |
ScrollToTop |
Fixed-position button that scrolls the page to the top on click, following the GNOME Human Interface Guidelines. | ✅ | — | Docs |
SearchBar |
Collapsible search bar following the Adwaita AdwSearchBar pattern. |
✅ | ⬜ | Docs |
SecurityMetric |
— | — | Docs | |
SegmentedBar |
Horizontal bar split into proportional segments, one per category. | ✅ | — | Docs |
Separator |
Thin dividing line that separates groups of content. | ✅ | ✅ | Docs |
SeverityBadge |
Pill-shaped label for vulnerability severities in security reports, CVE tables, dashboards, and scanner results. | — | — | Docs |
ShortcutLabel |
Read-only display of a keyboard shortcut with per-key key-cap styling. | 🚫 | — | Docs |
ShortcutsDialog |
Modal dialog listing keyboard shortcuts grouped in sections, with integrated search. | 🚫 | — | Docs |
Sidebar |
Lateral navigation panel following the Adwaita .navigation-sidebar pattern. |
✅ | — | Docs |
Skeleton |
Content-shaped loading placeholder for skeleton screens. | ✅ | ✅ | Docs |
Slider |
Draggable range control following the Adwaita GtkScale pattern. |
✅ | ✅ | Docs |
SpinButton |
Numeric input with − and + buttons following the Adwaita GtkSpinButton style. |
✅ | ✅ | Docs |
Spinner |
Indeterminate loading indicator following the Adwaita spinner style. | ✅ | ✅ | Docs |
SpinRow |
Settings row with an integrated spin button for numeric values. | ✅ | — | Docs |
SplitButton |
Primary action button with an attached dropdown arrow. | ✅ | — | Docs |
StatusBadge |
Pill-shaped text label for entity status. Use for human-readable state labels like published, beta, or new — not for numeric counts (use Badge for those). |
✅ | — | Docs |
StatusPage |
Empty-state and status page following the Adwaita AdwStatusPage pattern. |
✅ | — | Docs |
StepIndicator |
Numbered "Step X of Y" progress indicator for onboarding/wizard flows. | ✅ | ✅ | Docs |
Switch |
On/off toggle following the Adwaita switch style. | ✅ | ✅ | Docs |
SwitchRow |
Activatable row with an integrated switch. | ✅ | ✅ | Docs |
Tabs |
Tab-based navigation following the Adwaita AdwTabBar pattern. |
✅ | ✅ | Docs |
TagInput |
Type-to-add multi-value input rendering entries as removable Chips in a WrapBox. |
✅ | ⬜ | Docs |
TerminalView |
Scrollable terminal-style output area styled after GNOME Terminal. Intended for displaying logs, command output, or read-only text content. | ⬜ | — | Docs |
Text |
Typography component mirroring all Adwaita text style classes. | ✅ | — | Docs |
TextField |
Single-line text input with label, helper text, and error state. | ✅ | ✅ | Docs |
TextTruncate |
Single/multi-line text truncation with an automatic tooltip revealing the full content on overflow — mirrors GtkLabel's ellipsize property. |
⬜ | ✅ | Docs |
Timeline |
Ordered sequence of events connected by a visual timeline. | ✅ | — | Docs |
TimePicker |
Hour/minute selection built from paired SpinButtons inside a Popover, behind an entry-styled trigger — mirrors the GtkSpinButton + GtkPopover composition GNOME apps use for time entry, with 12- and 24-hour support. |
⬜ | — | Docs |
Toast |
Non-blocking temporary notification following the Adwaita AdwToast pattern. |
✅ | ✅ | Docs |
ToggleGroup |
Mutually-exclusive group of toggle buttons for in-place option selection. | ✅ | — | Docs |
Toolbar |
Horizontal action bar following the libadwaita .toolbar pattern. |
✅ | ✅ | Docs |
ToolbarView |
Layout container that attaches bars at the top and/or bottom while scrolling only the middle content. | ⬜ | — | Docs |
Tooltip |
Informational floating label following the GNOME HIG tooltip pattern. | ✅ | ✅ | Docs |
ViewSwitcher |
Segmented control for switching between major views, mirroring the Adwaita AdwViewSwitcher. |
✅ | ✅ | Docs |
ViewSwitcherBar |
Bottom navigation bar for ViewSwitcher items on narrow screens (≤ 550 px), mirroring AdwViewSwitcherBar. |
⬜ | — | Docs |
ViewSwitcherSidebar |
Sidebar-style view switcher for apps with many top-level views or when the sidebar layout fits better than a header-bar ViewSwitcher. |
⬜ | — | Docs |
VisuallyHidden |
Reusable "sr-only" utility — visually hides content while keeping it in the accessibility tree, so screen readers still announce it. | ⬜ | — | Docs |
VulnerabilityFinding |
— | — | Docs | |
VulnerabilitySummary |
— | — | Docs | |
WidgetManager |
Card that manages a controlled collection of "widgets" picked from a catalog, each rendering its own content via render(). The header's edit button toggles a dashed "add widget" trigger that opens a catalog picker — Modal, BottomSheet, or Drawer, chosen with pickerSurface. Adding and removing is staged inside the picker and only applied through onChange when the user confirms; canceling discards the staging. Widgets can only be removed through the picker, not inline in the card. |
✅ | — | Docs |
WindowTitle |
Two-line title + subtitle widget for use inside a HeaderBar. |
⬜ | — | Docs |
WrapBox |
Flexible wrapping layout container. | ✅ | ⬜ | Docs |
Layout shells & dashboard (@gnome-ui/layout)¶
Live examples and documentation: Storybook →
| Component | Description | Story |
|---|---|---|
ActivityFeed |
Chronological list of recent events with relative timestamps, optional icons, skeleton loading state, and a "Show more" affordance. | Docs |
AdaptiveLayout |
Full-page adaptive shell that switches navigation automatically based on viewport width. Use the viewport toolbar to preview each breakpoint: | Docs |
AppHeader |
GNOME application header with named shell slots. | Docs |
ApplicationCard |
App detail header with avatar, name, badge, description, stat row, and actions. Designed for the MyApps AppDetail view — use EntityCard for list rows. |
Docs |
Banner |
Persistent in-app message strip shown at the top of a view, following GNOME HIG banner guidelines. | Docs |
ChartCard |
Docs | |
CounterCard |
Metric card with an animated numeric counter. | Docs |
DashboardGrid |
Responsive 12-column grid container for dashboard widgets and panels. | Docs |
EmptyState |
Centered empty-state illustration for views with no data. | Docs |
EntityCard |
Avatar/icon + title + meta card. Covers both compact grid cards (Following screen) and full-width list rows (MyApps screen) via additive optional props. | Docs |
ErrorState |
Error state with four presets that set a default icon and title. All defaults can be overridden via icon and title props. |
Docs |
FileManager |
GNOME Files (Nautilus)–style file browser assembled from @gnome-ui/layout and @gnome-ui/react components. |
Docs |
IconBadge |
Rounded-square tinted icon container. Accepts the seven gnome-ui named colors or any hex value (#rgb / #rrggbb). In both cases the background is rendered at 15% opacity via color-mix. |
Docs |
Layout |
Full-page application shell from @gnome-ui/layout that composes four named zones following the GNOME Human Interface Guidelines. |
Docs |
LoadingStatus |
Visually hidden live region announcing a skeleton loading state to screen readers. | Docs |
MasonryGrid |
Masonry layout that distributes variable-height items across columns using a shortest-column-first algorithm — each new item is placed in the column with the least accumulated height, minimising gaps. | Docs |
PageContent |
Page content container with GNOME spacing and optional width clamping. | Docs |
PanelCard |
Card with a structured header / body / footer layout and built-in collapse/expand behaviour. | Docs |
ProfileCard |
Dashboard card for displaying a user profile — avatar, name, handle, optional status dot, optional stats row, and an optional decorative background chart. | Docs |
ProgressCard |
Resource usage card with a labeled progress bar. | Docs |
QuickActions |
Grid of shortcut action buttons for dashboards, file managers, and control panels. | Docs |
ResizablePanel |
Two or more panels separated by a draggable divider, based on the GtkPaned pattern. Foundational for user-resizable master-detail layouts (code editors, file explorers, analytics dashboards). |
Docs |
SectionHeader |
Title row for dashboard sections with optional subtitle and trailing action slot. | Docs |
Settings |
GNOME Settings–style preferences app assembled from @gnome-ui/layout and @gnome-ui/react. |
Docs |
SidebarShell |
Full-height GNOME sidebar with fixed header/footer and scrollable navigation area. | Docs |
SidebarTrigger |
Header button that opens overlay sidebars on narrow screens and toggles rail collapse on wider screens. | Docs |
SplitLayout |
List/master + detail shell following the Adwaita AdwNavigationSplitView pattern, with a HeaderBar for each pane — the way real Adwaita apps (Settings, Files, Contacts) actually look, rather than the bare pane-toggle mechanics of @gnome-ui/react's NavigationSplitView that this composes. |
Docs |
StatCard |
Metric card for dashboards with optional unit, trend indicator, icon, background chart, and loading state. | Docs |
StatusBar |
Compact footer/status bar for application shells. | Docs |
StatusIndicator |
Status dot for communicating the health of a service, connection, or resource. | Docs |
StickyToc |
Sticky table-of-contents side rail with scroll-spy: the link for the section currently nearest the top of the viewport is highlighted automatically as the user scrolls. For long docs/settings pages. | Docs |
TeamCard |
Group identity card: avatar group, team name, and member count. | Docs |
Toast |
In-app notifications following the GNOME Human Interface Guidelines. | Docs |
UserCard |
User identity panel for popovers, sidebar footers, and profile pages. | Docs |
Data visualization (@gnome-ui/charts)¶
Live examples and documentation: Storybook →
| Component | Description | Story |
|---|---|---|
AreaChart |
Area chart built on Recharts with GNOME design tokens, supporting stacked areas and gradient fills. | Docs |
BarChart |
Bar chart built on Recharts with GNOME design tokens for grouped comparisons across categories. | Docs |
BoxPlot |
Box-and-whisker plot built with plain HTML/CSS — no Recharts (it has no native box-plot primitive). Shows the distribution of one or more groups: median, interquartile range (Q1–Q3), whiskers extending to the most extreme non-outlier value, and outliers beyond 1.5×IQR. | Docs |
BulletChart |
Bullet graph (Stephen Few) built with plain SVG-free HTML — no Recharts. Shows a performance measure against a target and qualitative ranges in a single compact horizontal track, for KPI rows in tables and dashboards where GaugeChart takes too much vertical space. |
Docs |
CloudChart |
Word/tag cloud that scales each term's font size proportionally to its numeric value. | Docs |
ComposedChart |
Mixed chart combining bars, lines, and areas on shared axes. | Docs |
FunnelChart |
Funnel visualization for conversion rates and sales pipelines. | Docs |
GaugeChart |
Single-value speedometer gauge built on Recharts. Renders a semicircular arc between min and max, with the current value shown as a label at its center — for KPI dashboards, alongside StatCard from @gnome-ui/layout. |
Docs |
Heatmap |
Generic matrix heatmap built in pure CSS/SVG (no Recharts dependency) — for correlation matrices, density grids, or any row × column value grid. For a calendar-shaped activity heatmap, use ContributionGraph from @gnome-ui/react instead. |
Docs |
LineChart |
Line chart built on Recharts with GNOME design tokens for axes, grid, and tooltips. | Docs |
PieChart |
Pie and donut chart built on Recharts for part-to-whole comparisons. | Docs |
RadarChart |
Radar (spider) chart built on Recharts for comparing multiple attributes across one or more subjects. | Docs |
RadialBarChart |
Radial bar chart built on Recharts. Each data item renders as a circular arc, useful for showing multiple metrics as circular progress rings. | Docs |
SankeyChart |
Flow diagram built on Recharts. Renders named nodes as columns of rectangles connected by curved, proportionally-sized links — for multi-stage funnels, user journeys, or any flow between categories. | Docs |
ScatterChart |
Scatter and bubble chart for visualizing correlation between two numeric variables. | Docs |
TreeMap |
Tree map built on Recharts. Displays hierarchical data as nested rectangles; area is proportional to each item's value. | Docs |
WaterfallChart |
Floating-bar chart built on Recharts for the cumulative effect of a sequence of increases and decreases — revenue bridges, budget breakdowns, cohort attrition. Each bar starts where the previous one ended; mark isTotal on start/end/subtotal bars to anchor them to zero instead. |
Docs |
See ROADMAP.md for the full list of planned components.
Development¶
Prerequisites¶
- Node.js 22+
- npm 10+
Setup¶
Commands¶
| Command | Description |
|---|---|
npm run build |
Build all packages |
npm run storybook |
Start Storybook dev server at localhost:6006 |
npm run build-storybook |
Build Storybook for production |
npm run typecheck |
Type-check all packages |
npm run lint |
Lint all packages |
Project structure¶
gnome-ui/
├── packages/
│ ├── core/ # @gnome-ui/core — CSS design tokens
│ ├── icons/ # @gnome-ui/icons — Adwaita icon definitions (SVG path data)
│ ├── react/ # @gnome-ui/react — React components
│ ├── layout/ # @gnome-ui/layout — Application shell & dashboard components
│ ├── platform/ # @gnome-ui/platform — GNOME host bridge (GSettings, portals…)
│ ├── hooks/ # @gnome-ui/hooks — React hooks for platform APIs
│ └── charts/ # @gnome-ui/charts — Adwaita-styled chart components
├── GNOME_GUIDELINES.md
├── ROADMAP.md
└── turbo.json
Contributing¶
Read CONTRIBUTING.md before opening a pull request.
This project uses Conventional Commits. Your commit messages determine the next version automatically via semantic-release:
| Prefix | Release |
|---|---|
feat: |
minor |
fix:, perf:, refactor: |
patch |
feat!: or BREAKING CHANGE: |
major |
chore:, docs:, test: |
no release |
License¶
MIT © el_jijuna