SpaceUI API reference

Autocomplete

A text field that offers matching rows as you type. It holds no data of its own. Give it options and it renders them, highlights one, moves that highlight with the arrow keys, and calls onSelect when a row is chosen — however those options were produced. The list is a popover rather than a block in the flow: results that appear mid-keystroke and push the page down under the cursor are disorienting, and whatever is being searched usually sits directly below the field.

import { Autocomplete } from "@inkorange/space-ui";

Props

Also accepts every attribute of Omit< React.InputHTMLAttributes<HTMLInputElement>, "value" | "onChange" | "onSelect" | "className" | "style" > — 303 inherited props.

AutocompleteOption

The shape behind options, onSelect.

Tokens

Badge

A compact status label. Colour is the message, so choose it for meaning: the semantic roles say safe, pending or destructive, while the categorical hues only tell one kind of thing from another and carry no judgement. Single-line by default, since a badge that wraps stops reading as a badge. Opt into wrap for free text you do not control.

import { Badge } from "@inkorange/space-ui";

Props

Also accepts every attribute of SpacingProps and Omit<React.HTMLAttributes<HTMLSpanElement>, "color"> — 281 inherited props.

BarList

A ranked list of values as bars: a label, a track, a filled bar, a figure. For results read against each other — a poll, the top ten by some measure, a breakdown of a total. It is the form to reach for when the category names are words rather than dates: they get a column of their own and stay readable, where a vertical bar chart would turn them on their side. No axis and no grid, because there is nothing to measure against but the other rows: every bar is drawn against the longest one, or against max when the share of a known total is the point.

import { BarList } from "@inkorange/space-ui";

Props

Also accepts every attribute of Omit<React.HTMLAttributes<HTMLDivElement>, "onSelect"> — 276 inherited props.

BarListItem

The shape behind items, onItemClick.

Tokens

Box

A plain div that understands the spacing scale. The escape hatch for when you need margin or padding on the grid but no layout behaviour with it. Renders nothing of its own — no class, no styling — so it never interferes with whatever you put inside.

import { Box } from "@inkorange/space-ui";

Props

Also accepts every attribute of SpacingProps and React.HTMLAttributes<HTMLDivElement> — 282 inherited props.

Button

The thing a reader presses to make something happen. A glass capsule whose rim glows like a planet's sunlit limb, with stars twinkling inside it and a glint that sweeps across it now and then. It renders a plain <button> and forwards its ref, so it drops into anything that needs to borrow a trigger — a dialog, a menu, a router link's render prop — without a wrapper in between.

import { Button } from "@inkorange/space-ui";

Props

Also accepts every attribute of React.ButtonHTMLAttributes<HTMLButtonElement> — 288 inherited props.

Card

A translucent panel for grouping related content, one step above the page surface. Its 12px inset is a deliberate exception to the 8pt grid, kept for parity with the app this was extracted from. Pass image for a media card. The image is framed by the card rather than being an ordinary child, so every card in a row reserves the same box before its image loads and none of them reflow when it does.

import { Card } from "@inkorange/space-ui";

Props

Also accepts every attribute of SpacingProps and React.HTMLAttributes<HTMLDivElement> — 282 inherited props.

Tokens

Carousel

A row of slides that scrolls sideways, with arrows and optional dots. The browser does the heavy lifting. The row is a native horizontal scroller with CSS scroll snapping, so a flick on a phone uses the platform's own momentum and lands on a slide, and nothing runs per frame while it moves. Slide widths come from a CSS calculation on the view count, so a breakpoint can change how many fit without React knowing. A mouse can drag the row too. It follows the pointer, then glides to the next stop in the direction it was dragged; a drag never clicks a link or button in the slide it ends on. ## Responsive view count The number of slides in view is a design token, not state. Vary it by screen width in CSS; never by swapping perView from a resize listener or matchMedia, which re-renders, and can disagree with the server render. 1. Pass perView for the widest layout. 2. Set --sp-carousel-view-count on a class (or any ancestor) in media or container queries for the other widths. Fractions are fine. 3. Nothing else. Widths are computed in CSS, and the arrows, dots and page size are measured from the rendered row whenever it resizes. Precedence: --sp-carousel-view-count from a stylesheet, then perView, then 1. The prop is passed as a private default (--_view-count-default), not as the public token, precisely so a stylesheet can override it. Setting the token on :root overrides perView on every carousel in the app; scope it to a class or section instead. --sp-carousel-gap-size can be varied the same way.

import { Carousel } from "@inkorange/space-ui";

Props

Also accepts every attribute of Omit<React.HTMLAttributes<HTMLElement>, "children"> — 276 inherited props.

Tokens

Chart

A chart of one or more datasets over a shared set of categories — as bars, a line, or a filled area. Drawn as plain SVG from the library's own arithmetic: no charting dependency, and every colour, size and radius is a token, so a chart is the same material as the rest of the page. The series palette is an order rather than a pool. The first series is always the first colour, so hiding one never repaints the others. What it does without being asked: a legend once there is more than one series, a crosshair reading every series at the category under the pointer, and a table of the same numbers for screen readers. What it refuses to do: a second y axis. Two measures on different scales belong in two charts — one pair of axes can be drawn to tell any story you like.

import { Chart } from "@inkorange/space-ui";

Props

Also accepts every attribute of Omit<React.HTMLAttributes<HTMLDivElement>, "onClick"> — 276 inherited props.

ChartSeries

The shape behind series.

ChartPoint

The shape behind onPointClick.

Tokens

Checkbox

A single yes/no choice: accepting terms, turning one setting on. For a set of options where several can be chosen, wrap CheckboxGroup around CheckboxGroup.Items and hold one array instead of a boolean each.

import { Checkbox } from "@inkorange/space-ui";

Props

Tokens

Checkbox.CheckboxGroup

import { Checkbox } from "@inkorange/space-ui";

Props

Tokens

Dialog

A modal window over the page, for a task that has to finish or be abandoned before anything else happens. It rides the platform's own <dialog>, so the backdrop, the top layer, the Escape key and the focus trap are the browser's rather than an approximation of them. Opening moves focus inside; closing returns it to whatever opened it. For a decision with consequences — deleting, discarding, overwriting — reach for AlertDialog, which refuses to close by a click outside, so a misplaced click cannot answer the question for the reader. Compose it from the parts hanging off this name: Dialog.Trigger, Dialog.Content, Dialog.Title, Dialog.Description and Dialog.Close.

import { Dialog } from "@inkorange/space-ui";

Props

Dialog.Close

Closes the dialog. Same shape as Trigger: wraps its child, adds a close on click, and adds no markup.

import { Dialog } from "@inkorange/space-ui";

Props

Dialog.Content

The dialog surface. Built on the native <dialog> element, so the browser supplies the top layer, focus trapping and Escape handling rather than the library reimplementing them. Dismissible by Escape or a click on the backdrop; AlertDialog's Content deliberately is not.

import { Dialog } from "@inkorange/space-ui";

Props

Also accepts every attribute of React.HTMLAttributes<HTMLDialogElement> — 277 inherited props.

Dialog.Trigger

Opens the dialog. Chains onto its child's existing click handler rather than replacing it, and renders no element of its own — so the child stays whatever it already was, button or otherwise.

import { Dialog } from "@inkorange/space-ui";

Props

DropdownMenu

A button that opens a list of actions. Actions, not choices: every item does something when picked, and nothing in the menu holds a value. For choosing one of a set of values, that is Select, which looks similar and means something entirely different to a screen reader. Arrow keys move through the items, Home and End jump to the ends, Escape closes and returns focus to the button, and typing a letter jumps to the next item starting with it. The panel uses the browser's popover layer, so it stacks above the page without a z-index to maintain. Compose it from DropdownMenu.Item, DropdownMenu.Label and DropdownMenu.Separator.

import { DropdownMenu } from "@inkorange/space-ui";

Props

Also accepts every attribute of Omit<ButtonProps, "children"> — 292 inherited props.

Flex

A flex row or column whose gap comes from the spacing scale, so layouts inherit the 8pt grid instead of restating it in pixels. asChild merges the layout onto its only child rather than adding a wrapper, for when an extra div would break a grid or a selector.

import { Flex } from "@inkorange/space-ui";

Props

Also accepts every attribute of SpacingProps and React.HTMLAttributes<HTMLDivElement> — 282 inherited props.

Grid

A simple column grid, 1-3 wide, with the same gap scale as Flex. Pass an object to columns for responsive counts. Deliberately narrow: anything more elaborate is a job for CSS grid directly rather than a prop API that would end up reinventing it.

import { Grid } from "@inkorange/space-ui";

Props

Also accepts every attribute of SpacingProps and React.HTMLAttributes<HTMLDivElement> — 282 inherited props.

Tokens

Heading

A section heading. as sets the heading level and size sets the appearance, deliberately apart — so a visually small heading can still be an h2 where the document structure calls for one. Shares size steps 4-6 with Text, so a heading and body copy on the same line align.

import { Heading } from "@inkorange/space-ui";

Props

Also accepts every attribute of SpacingProps and Omit<React.HTMLAttributes<HTMLHeadingElement>, "color"> — 281 inherited props.

IconToggle

A segmented icon toggle: every option visible at once in a single pill, the selected one reading as active, and a click on any of them selecting it. Reach for it to switch between modes or views of the same thing, where the options are few and each has an obvious glyph. The alternative pattern — one button that shows the mode you are NOT in and swaps its own icon on click — is deliberately not what this does: the control's meaning changes under the cursor, and nobody can tell whether the icon means "you are here" or "go here". Generic over the option set, so the values stay your own union type.

import { IconToggle } from "@inkorange/space-ui";

Props

IconToggleOption

The shape behind options.

Tokens

Link

An inline anchor, styled to sit inside running text without disturbing its rhythm. Sizes match Text's first three steps. Use asChild to wrap a router's own link component rather than nesting two anchors, which is invalid and breaks keyboard navigation.

import { Link } from "@inkorange/space-ui";

Props

Also accepts every attribute of SpacingProps and Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, "color"> — 289 inherited props.

Loader

An orbital spinner, for work whose length you cannot measure: a small pulsing planet at the centre of a static ring, with a moon travelling it. Where you CAN measure the work, use Progress instead — a spinner that could have been a bar tells the reader less than it knows. The motion is pure CSS and runs on the compositor, so it keeps turning smoothly while the main thread is busy doing the thing it is waiting on — which is exactly when a loader is on screen.

import { Loader } from "@inkorange/space-ui";

Props

Tokens

Message

A banner that tells the reader something about the state of the page — a risk, a result, a failure. The three variants do not merely change hue. info is lit like the rest of the system, cool and calm; warning warms the rim to amber; alert uses the ember treatment, the same warm limb the destructive Button wears. Each carries its own glyph so the kind of message reads before the words do. For a decision the reader must make, reach for AlertDialog instead — a message states, it does not ask.

import { Message } from "@inkorange/space-ui";

Props

Also accepts every attribute of Omit<React.HTMLAttributes<HTMLDivElement>, "title"> — 276 inherited props.

Tokens

Pagination

Page-by-page navigation for a long list. Holds no state: give it the pagination object you already have and it reports which page was clicked. Every control is the same limb-lit glass as Select and Button, but only the current page's rim orbits. Nine arcs turning in one row would be noise; one turning is where you are. Previous and Next stay in place when they cannot be used, so the numbers never slide sideways on the first and last page.

import { Pagination } from "@inkorange/space-ui";

Props

Also accepts every attribute of Omit<React.HTMLAttributes<HTMLElement>, "children"> — 277 inherited props.

PaginationState

The shape behind pagination.

Tokens

PieChart

Parts of a whole, as a circle. Worth saying plainly: a pie is the weakest way to compare sizes — people read angles badly — and it is the wrong chart for more than a handful of slices, for values that are not parts of one total, or for change over time. Where the comparison is the point, BarList is easier to read. Where a pie is right is a whole that splits a few ways and a reader who needs to see "most of it" at a glance. So this one is built to stay readable: every slice keeps a hairline of the surface between it and its neighbour, the legend carries the names and the figures, and a donut puts the total in the middle where it can be read exactly rather than estimated.

import { PieChart } from "@inkorange/space-ui";

Props

Also accepts every attribute of Omit<React.HTMLAttributes<HTMLDivElement>, "onSelect"> — 276 inherited props.

PieSlice

The shape behind slices, onSliceClick.

Tokens

Popover

A button that opens a floating panel of anything — a small form, a set of filters, a prompt — without leaving the page. It rides the browser's own popover layer, so the panel stacks above everything without a z-index arms race and closes on Escape or a click elsewhere by the platform's rules rather than an approximation of them. It sits next to its trigger, flips above it when there is no room below, and stays attached to it if the page scrolls or the layout around it shifts. Opening moves focus into the panel so a keyboard user lands on its first control; closing with Escape hands focus back to the trigger. The panel is labelled by the trigger, so it announces as what the button said it was.

import { Popover } from "@inkorange/space-ui";

Props

Also accepts every attribute of Omit<ButtonProps, "children"> — 292 inherited props.

Tokens

Progress

A determinate bar for work you can measure — use Loader when you cannot. Speaks the same visual language as Slider, because a progress bar and a slider track are the same object: one you watch, one you drag.

import { Progress } from "@inkorange/space-ui";

Props

Also accepts every attribute of React.HTMLAttributes<HTMLDivElement> — 278 inherited props.

Tokens

RadioGroup

Exactly one choice from a set you can see all of at once. Use it where the options matter enough to be read side by side and there are few enough to show — up to about seven. Past that a Select keeps the page calm. Where several answers can be true at the same time, that is CheckboxGroup. Hold the chosen value and pass onValueChange. Each orb ignites when it is chosen, arrow keys move between the options the way a native radio group does, and a label that wraps to two lines keeps its orb beside the first line rather than drifting to the middle. Compose it from RadioGroup.Item.

import { RadioGroup } from "@inkorange/space-ui";

Props

Tokens

Select

Choosing one value from a list, with the list kept out of the way until it is wanted. The right control when the options are many, or dull, or both — a country, a size, a sort order. Where there are few options and each one deserves to be read, RadioGroup shows them all without a click. Where the items are actions rather than values, that is DropdownMenu. The panel opens on the browser's popover layer, which is what lets it escape a dialog, a transformed ancestor or a clipping overflow and sit above the page at its full height. It flips above the trigger when there is no room below, follows the trigger if the page scrolls, and closes on Escape with focus handed back. Typing jumps to a matching option. Compose it from Select.Item.

import { Select } from "@inkorange/space-ui";

Props

Also accepts every attribute of Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "value" | "children" | "onChange"> — 284 inherited props.

Tokens

Separator

A hairline rule for dividing content within a surface, where a full panel boundary would be too heavy. Exposed as role="separator", so assistive technology hears the division too.

import { Separator } from "@inkorange/space-ui";

Props

Also accepts every attribute of React.HTMLAttributes<HTMLSpanElement> — 278 inherited props.

Slider

A range control: one thumb for a value, two for a span between values. Each thumb is a real <input type="range">, so arrow keys, Home, End and Page Up/Down all work without this component reimplementing them, and a screen reader announces a slider because it is one. What is drawn — the glass tube, the lit fill, the little planet of a thumb — sits on top of inputs that are invisible but still doing the work. With two thumbs they cannot cross: each is clamped to the other, so the array stays in order and a range can never read back inverted. minDistance keeps a gap between them where a zero-width range would be meaningless.

import { Slider } from "@inkorange/space-ui";

Props

Tokens

Tabs

Several panels sharing one piece of the page, one visible at a time. Right for views of the same subject that a reader moves between and compares — overview, history, settings for one record. Wrong for steps in a sequence, where the reader needs to know how far along they are, and wrong for content that should be findable by search or linkable on its own: a hidden panel is invisible to both. Arrow keys move between the tabs, Home and End jump to the ends, and only the selected tab is in the tab order, so one press of Tab leaves the strip for the panel instead of walking every tab in it. Compose it from Tabs.List, Tabs.Trigger and Tabs.Content.

import { Tabs } from "@inkorange/space-ui";

Props

Tokens

Text

Body copy. Size, weight and colour are presentational and independent of the element, so as stays free to be whatever the document actually needs — a p for prose, a label for a field, a span inline. Colour is a role, not a hue: use muted for secondary copy and reserve the status roles for text that genuinely carries that meaning.

import { Text } from "@inkorange/space-ui";

Props

Also accepts every attribute of SpacingProps and Omit<React.HTMLAttributes<HTMLElement>, "color"> — 281 inherited props.

TextArea

Multi-line text entry. rows sets the initial height; it grows with its container's width and resizes vertically only, since horizontal drag would break the surrounding layout.

import { TextArea } from "@inkorange/space-ui";

Props

Also accepts every attribute of Omit<React.TextareaHTMLAttributes<HTMLTextAreaElement>, "className" | "style"> — 290 inherited props.

TextField

A single line of text the reader types. A real <input> underneath, so value, onChange, type, required, autoComplete and the rest of the native attributes all work as they already do, and the browser's own autofill and validation come along with them. For more than a line, use TextArea. Put an icon, a unit or a small button beside the text with TextField.Slot. It sits inside the field's rim and keeps its own padding, so the text never runs underneath it.

import { TextField } from "@inkorange/space-ui";

Props

Also accepts every attribute of Omit<React.InputHTMLAttributes<HTMLInputElement>, "className" | "style"> — 305 inherited props.

Tooltip

A short label revealed on hover or focus, for naming a control whose icon is not self-evident. Never put information here that a reader needs: a tooltip is unreachable on touch and easy to miss. If it must be read, put it on the page.

import { Tooltip } from "@inkorange/space-ui";

Props

Icons

23 icons ship from the same entry point as React components taking the standard SVG props.

• BookmarkIcon
• ChatBubbleIcon
• CheckIcon
• ChevronDownIcon
• ChevronLeftIcon
• ChevronRightIcon
• ChevronUpIcon
• CrossCircledIcon
• EnterFullScreenIcon
• ExclamationTriangleIcon
• ExitFullScreenIcon
• HeartFilledIcon
• HeartIcon
• InfoCircledIcon
• MagnifyingGlassIcon
• MinusIcon
• Pencil1Icon
• PersonIcon
• PlusIcon
• QuestionMarkCircledIcon
• Share2Icon
• TrashIcon
• XIcon