@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