@gnome-ui/react

@gnome-ui/react

React component library following the GNOME Human Interface Guidelines, built on the Adwaita design language.

Live documentation: Storybook →

Installation

npm install @gnome-ui/react

Setup

Import the stylesheet once at the root of your app:

// main.tsx or App.tsx
import "@gnome-ui/react/styles";

Quick example

import { Button, TextField, Dialog } from "@gnome-ui/react";
import "@gnome-ui/react/styles";

export default function App() {
  return (
    <Button variant="suggested" onClick={() => console.log("saved")}>
      Save Changes
    </Button>
  );
}

Components

Controls

Component	Description
Button	Default, Suggested, Destructive, Flat, Raised variants; osd overlay modifier; sm/md/lg sizes; pill and circular shapes
SplitButton	Primary action button with attached dropdown arrow; Default, Suggested, Destructive variants
Switch	On/off toggle for settings that apply immediately
Checkbox	Multi-selection with checked, unchecked, and indeterminate states
RadioButton	Single-selection within a group; keyboard arrow-key navigation
TextField	Text input with label, helper text, and error state
SpinButton	Numeric input with −/+ buttons, keyboard nav, decimal support
Slider	Draggable range control with tick marks, decimal steps, and keyboard nav
Dropdown	Expandable option list with keyboard nav, flip positioning, and descriptions
SearchBar	Collapsible search bar with auto-focus, clear button, filter row, and inline variant
Link	Inline hyperlink with accent colour, animated underline, and external-URL variant
ToggleGroup / ToggleGroupItem	Mutually-exclusive toggle buttons; icon-only, label-only, or icon + label
InlineViewSwitcher / InlineViewSwitcherItem	Compact inline view switcher; default, flat, and round variants

Display

Component	Description
Text	12 Adwaita type styles: large-title, title-1…4, heading, body, caption…
Icon	React adapter for @gnome-ui/icons — inline SVG, inherits currentColor
Avatar	Circular user image with deterministic-color initials fallback
Badge	Counter or status dot, optionally anchored over another element
Spinner	Indeterminate loading indicator; sm/md/lg sizes
ProgressBar	Determinate (0–1) and indeterminate progress indicator
StatusPage	Empty-state page with icon, title, description, and optional actions; compact prop for sidebars/popovers
Separator	Horizontal/vertical dividing line between content groups
Chip	Compact pill-shaped label for tags, filters, and multi-select; static, removable, and selectable modes

Layout & containers

Component	Description
Card	Elevated surface for grouping content; static or interactive (activatable)
Frame	Bordered surface without background fill — mirrors GtkFrame
HeaderBar	Title bar with centered title and leading/trailing action slots
Toolbar	Horizontal action bar with 6 px padding/gap for flat and raised buttons
Spacer	Invisible flex: 1 filler to push trailing items to the end of a Toolbar
LinkedGroup	Renders children as a single connected unit with merged borders; horizontal and vertical
Sidebar / SidebarSection / SidebarItem	Lateral navigation panel with named sections, suffix widgets, and context menus
ActionRow	Settings row with title, subtitle, leading icon, and trailing widget
ButtonRow	Full-width activatable row styled as a button inside a BoxedList; Default, Suggested, Destructive
ExpanderRow	Collapsible ActionRow that reveals nested rows; controlled and uncontrolled
BoxedList	Rounded bordered list of rows — canonical GNOME settings pattern
WrapBox	Flexible wrapping layout for tag/chip lists that flows across multiple lines
TabBar / TabItem / TabPanel	Tab-based navigation with keyboard support, optional close buttons, and inline variant
ViewSwitcher / ViewSwitcherItem	Segmented pill control for switching between 2–4 top-level views
ViewSwitcherSidebar / ViewSwitcherSidebarItem	Sidebar-based view switcher — replaces GtkStackSidebar
ShortcutsDialog	Modal listing keyboard shortcuts with integrated search

Overlays

Component	Description
Toast / Toaster	Non-blocking temporary notification with auto-dismiss, action, and queue support
Dialog	Blocking modal with title, body, focus trap, and configurable buttons
Tooltip	Floating informational label on hover/focus with auto-flip positioning
Popover	Floating interactive panel with arrow and auto-flip positioning
Banner	Persistent message strip with optional action and dismiss

Adaptive layout

Component	Description
useBreakpoint	Hook tracking viewport width against GNOME breakpoints (400 / 550 / 860 px)
Clamp	Constrains content to a max width, centering it — mirrors AdwClamp
NavigationSplitView	Two-pane layout that collapses to a single pane at ≤ 400 px
OverlaySplitView	Sidebar becomes slide-over overlay at ≤ 400 px
ViewSwitcherBar	Bottom bar for ViewSwitcher items on narrow screens (≤ 550 px)
BreakpointBin	Applies layout changes when the component crosses a size threshold — CSS container queries equivalent

License

MIT