# Creance

> An open-source React component library: 109 components in light, dark and solid themes, with a set built for supervising AI agents: approving what an agent wants to do, watching it work, reviewing its changes and taking back control. Under the MIT licence.

Every page below is markdown. https://creance.pages.dev/llms-full.txt has all of them in one file.

## Install and use

```sh
npm install @creance-ui/react @creance-ui/tokens
```

Import the tokens and the component styles once, at the root of the app, tokens first. Then import components by name.

```tsx
import '@creance-ui/tokens/tokens.css';
import '@creance-ui/react/styles.css';
import { Button } from '@creance-ui/react';
```

React 18 or later is the only peer dependency. The examples are written for the live editor on the site: `log` stands for any event handler, and names such as `state`, `set` and the sample data are provided by that editor.

## Getting started

- [Introduction](https://creance.pages.dev/docs/Introduction.md): What Creance is, what is in it, and where it stands.
- [Installation](https://creance.pages.dev/docs/Installation.md): Two packages from npm, and two stylesheets imported once.
- [Frameworks](https://creance.pages.dev/docs/Frameworks.md): Creance is a React library. This is where it has been tested, and where it has not.
- [Usage](https://creance.pages.dev/docs/Usage.md): Use a component on its own, or drive a whole screen from one stream of events.
- [Theming](https://creance.pages.dev/docs/Theming.md): Every colour, radius, shadow and font is a CSS variable. Change the variables and the components follow.
- [Accessibility](https://creance.pages.dev/docs/Accessibility.md): The target is WCAG 2.2 AA. This is what is in place, how it is checked, and what is not done.

## Project

- [Architecture](https://creance.pages.dev/docs/Architecture.md): One event stream in, plain props out, and the decisions behind the build.
- [Testing](https://creance.pages.dev/docs/Testing.md): The checks that run in CI on every push, with the figures from the latest commit.
- [Status](https://creance.pages.dev/docs/Status.md): On npm. The code is complete and passes its checks. This is what is not done.

## Components: Actions

- [Button](https://creance.pages.dev/docs/Button.md): A glass capsule. Blue is for the one primary action; red text marks refusal.
- [CopyButton](https://creance.pages.dev/docs/CopyButton.md): Copies text, shows a check for two seconds, and tells screen readers.
- [IconButton](https://creance.pages.dev/docs/IconButton.md): A button with only an icon. Its label is required and shows as a tooltip.
- [LoadMoreButton](https://creance.pages.dev/docs/LoadMoreButton.md): A full-width button under a list that says when it is loading.
- [ShowMore](https://creance.pages.dev/docs/ShowMore.md): Long content cut to a few lines, with a button to show the rest.
- [SplitButton](https://creance.pages.dev/docs/SplitButton.md): The common action, with alternatives in a menu.
- [TextWithCopy](https://creance.pages.dev/docs/TextWithCopy.md): Text with a copy button beside it.
- [Toggle](https://creance.pages.dev/docs/Toggle.md): A button that stays on or off.
- [ToggleGroup](https://creance.pages.dev/docs/ToggleGroup.md): A segmented control: pick one, or any.

## Components: Forms

- [Calendar](https://creance.pages.dev/docs/Calendar.md): A day or a range. Arrow keys move by day, Page Up and Down by month.
- [Checkbox](https://creance.pages.dev/docs/Checkbox.md): A native checkbox with its label.
- [Choicebox](https://creance.pages.dev/docs/Choicebox.md): Card-sized options for a choice that needs a sentence each.
- [ClearableInput](https://creance.pages.dev/docs/ClearableInput.md): A text field with a clear button that puts focus back in the field.
- [Combobox](https://creance.pages.dev/docs/Combobox.md): Type to filter and pick one. Arrow keys move, Enter picks, Escape closes.
- [Feedback](https://creance.pages.dev/docs/Feedback.md): Thumbs up or down, then an optional comment.
- [Field](https://creance.pages.dev/docs/Field.md): A label, a control, and the hint or error that describes it, wired for screen readers.
- [Input](https://creance.pages.dev/docs/Input.md): A text field.
- [MultiSelect](https://creance.pages.dev/docs/MultiSelect.md): Pick several. Picks become chips; Backspace removes the last one.
- [Radio](https://creance.pages.dev/docs/Radio.md): A native radio with its label.
- [RadioGroup](https://creance.pages.dev/docs/RadioGroup.md): One choice from a short list.
- [SearchInput](https://creance.pages.dev/docs/SearchInput.md): A search field with a shortcut hint, a spinner and a clear button.
- [Select](https://creance.pages.dev/docs/Select.md): The native select, styled. The operating system draws the menu.
- [Slider](https://creance.pages.dev/docs/Slider.md): One value, a range, or steps, read out in words.
- [Switch](https://creance.pages.dev/docs/Switch.md): An on/off setting that applies immediately.
- [Textarea](https://creance.pages.dev/docs/Textarea.md): A multi-line text field.
- [ThemeSwitcher](https://creance.pages.dev/docs/ThemeSwitcher.md): Light, dark or match the system. This one really switches this page.

## Components: Navigation

- [AppShell](https://creance.pages.dev/docs/AppShell.md): The frame of an app: sidebar, header, content and an optional aside.
- [Breadcrumbs](https://creance.pages.dev/docs/Breadcrumbs.md): Where you are. Long trails fold the middle.
- [Collapse](https://creance.pages.dev/docs/Collapse.md): Sections that open and close.
- [CommandMenu](https://creance.pages.dev/docs/CommandMenu.md): Search everything and act from the keyboard. Press ⌘K or Ctrl+K to see it in use: the search on this site is a CommandMenu.
- [ContextMenu](https://creance.pages.dev/docs/ContextMenu.md): Opens on right-click, long-press, or Shift+F10.
- [DotsMenu](https://creance.pages.dev/docs/DotsMenu.md): A "…" button with secondary actions for one row.
- [Footer](https://creance.pages.dev/docs/Footer.md): The end of a page: brand, groups of links, and a line for copyright.
- [Menu](https://creance.pages.dev/docs/Menu.md): Actions behind a button. Put destructive ones last, after a separator.
- [Navbar](https://creance.pages.dev/docs/Navbar.md): The bar across the top. When it gets narrow, the links move into a menu.
- [Pagination](https://creance.pages.dev/docs/Pagination.md): Page numbers, or a compact previous and next.
- [Scroller](https://creance.pages.dev/docs/Scroller.md): A horizontal strip that fades where there is more.
- [Sidebar](https://creance.pages.dev/docs/Sidebar.md): Links down the side, in groups. Collapses to icons that keep their names.
- [Steps](https://creance.pages.dev/docs/Steps.md): Where someone is in a fixed sequence. Each status has a shape and a spoken label.
- [Tabs](https://creance.pages.dev/docs/Tabs.md): A segmented control and its panels. Arrow keys move between tabs.

## Components: Overlays

- [ContextCard](https://creance.pages.dev/docs/ContextCard.md): A preview on hover or keyboard focus. Focus never moves into it.
- [DestructiveActionModal](https://creance.pages.dev/docs/DestructiveActionModal.md): For actions that cannot be undone. The red button stays off until the name is typed.
- [Dialog](https://creance.pages.dev/docs/Dialog.md): A question over a dimmed page. It traps focus and returns it when closed.
- [RelativeTimeCard](https://creance.pages.dev/docs/RelativeTimeCard.md): "2 hours ago", with the exact local and UTC time on hover or focus.
- [Sheet](https://creance.pages.dev/docs/Sheet.md): A panel that slides in from an edge.
- [Toast](https://creance.pages.dev/docs/Toast.md): A short message that rises from the bottom. Call toast() from anywhere.
- [Tooltip](https://creance.pages.dev/docs/Tooltip.md): Extra text on hover and keyboard focus.

## Components: Data display

- [Avatar](https://creance.pages.dev/docs/Avatar.md): Agents are rounded squares; people are circles.
- [Badge](https://creance.pages.dev/docs/Badge.md): A status as tone, icon and word.
- [Card](https://creance.pages.dev/docs/Card.md): A glass tile for grouping related content.
- [Code](https://creance.pages.dev/docs/Code.md): Inline code, or a scrollable block.
- [Description](https://creance.pages.dev/docs/Description.md): Terms and their values.
- [EmptyState](https://creance.pages.dev/docs/EmptyState.md): An empty list as an invitation to act.
- [Entity](https://creance.pages.dev/docs/Entity.md): An agent or a person as a row.
- [FileTree](https://creance.pages.dev/docs/FileTree.md): Files and folders with change markers. Arrow keys walk the tree.
- [Gauge](https://creance.pages.dev/docs/Gauge.md): A ring that fills to a percentage. Red only past a limit you set.
- [JsonView](https://creance.pages.dev/docs/JsonView.md): JSON as a tree you can fold.
- [Kbd](https://creance.pages.dev/docs/Kbd.md): A keyboard key.
- [MiddleTruncate](https://creance.pages.dev/docs/MiddleTruncate.md): Shortens the middle of a path or ID and keeps both ends.
- [ProgressBar](https://creance.pages.dev/docs/ProgressBar.md): Progress toward a known total.
- [Separator](https://creance.pages.dev/docs/Separator.md): A hairline between groups.
- [Snippet](https://creance.pages.dev/docs/Snippet.md): Shell commands with a copy button. The prompt sign is never copied.
- [StatusDot](https://creance.pages.dev/docs/StatusDot.md): A small mark and a word. Each status has its own shape as well as tone.
- [Table](https://creance.pages.dev/docs/Table.md): Sortable columns, row selection with Shift-click ranges, and bulk actions.

## Components: Feedback

- [Alert](https://creance.pages.dev/docs/Alert.md): A message in the page: what happened and what to do.
- [Banner](https://creance.pages.dev/docs/Banner.md): A full-width notice in three tones.
- [ErrorCard](https://creance.pages.dev/docs/ErrorCard.md): A failure that needs a decision: what broke, the error, and what you can do.
- [ErrorMessage](https://creance.pages.dev/docs/ErrorMessage.md): What went wrong and what to do next.
- [LoadingDots](https://creance.pages.dev/docs/LoadingDots.md): Three dots beside what is happening.
- [ProjectBanner](https://creance.pages.dev/docs/ProjectBanner.md): A project-wide notice with one action.
- [Skeleton](https://creance.pages.dev/docs/Skeleton.md): A placeholder while content loads.
- [Spinner](https://creance.pages.dev/docs/Spinner.md): Something is happening, with no known end.

## Components: Media

- [BrowserFrame](https://creance.pages.dev/docs/BrowserFrame.md): A browser window drawn around a preview.
- [PhoneFrame](https://creance.pages.dev/docs/PhoneFrame.md): A phone drawn around content, to show a component at phone size.
- [Video](https://creance.pages.dev/docs/Video.md): A player with glass controls. It starts muted and never autoplays.

## Components: Charts

- [BarChart](https://creance.pages.dev/docs/BarChart.md): Amounts across categories. More than one series stacks.
- [BarList](https://creance.pages.dev/docs/BarList.md): A ranking: a name, a bar and a value on every row.
- [DonutChart](https://creance.pages.dev/docs/DonutChart.md): Parts of a whole, with each slice’s value and share in the legend.
- [LineChart](https://creance.pages.dev/docs/LineChart.md): A trend over time. Point at it, or focus it and press the arrow keys.
- [Sparkline](https://creance.pages.dev/docs/Sparkline.md): A trend with no axes, for a table cell or a stat card.
- [StatCard](https://creance.pages.dev/docs/StatCard.md): One number, what it is, and how it moved.

## Components: Chat

- [Chat](https://creance.pages.dev/docs/Chat.md): A whole conversation with an agent: messages, suggestions and the input. Type something to try it.
- [Message](https://creance.pages.dev/docs/Message.md): One turn. Yours sit right in a tile; the agent’s are plain text under its name.
- [MessageList](https://creance.pages.dev/docs/MessageList.md): A scrolling column that follows new messages until you scroll up.
- [ModelPicker](https://creance.pages.dev/docs/ModelPicker.md): Chooses which model answers.
- [PromptInput](https://creance.pages.dev/docs/PromptInput.md): Where you write to an agent. Enter sends; Send becomes Stop while it works.
- [Reasoning](https://creance.pages.dev/docs/Reasoning.md): The agent’s thinking, folded away behind how long it took.
- [Sources](https://creance.pages.dev/docs/Sources.md): What an answer is based on, with numbered markers in the text.
- [Suggestions](https://creance.pages.dev/docs/Suggestions.md): Starting points above the input. Choosing one sends it.

## Components: Agent

- [AgentHandoffBanner](https://creance.pages.dev/docs/AgentHandoffBanner.md): The point where the agent hands control back: outcome, summary, next actions.
- [AgentRunLayout](https://creance.pages.dev/docs/AgentRunLayout.md): The run screen. It takes organisms as slots, so your app decides what goes where.
- [ApprovalPrompt](https://creance.pages.dev/docs/ApprovalPrompt.md): One specific action to allow or deny. A, Shift+A and D work while focus is inside it.
- [BudgetMeter](https://creance.pages.dev/docs/BudgetMeter.md): Spend against a limit. It warns at 80% and flags going over.
- [CheckpointRewind](https://creance.pages.dev/docs/CheckpointRewind.md): Pick a point to roll back to and see what it undoes before confirming.
- [ConfidenceMeter](https://creance.pages.dev/docs/ConfidenceMeter.md): How sure the agent is: a range in words with reasons, never a percentage.
- [DiffLine](https://creance.pages.dev/docs/DiffLine.md): One line of a diff, with line numbers and screen-reader text.
- [DiffReview](https://creance.pages.dev/docs/DiffReview.md): A decision per hunk before anything lands. J and K move, Y and N decide.
- [FleetSky](https://creance.pages.dev/docs/FleetSky.md): Many agents at once, as birds on lines back to you. The one that needs you flies in on a taut line.
- [KeyboardHint](https://creance.pages.dev/docs/KeyboardHint.md): A shortcut and what it does.
- [KillSwitch](https://creance.pages.dev/docs/KillSwitch.md): Hold for a second to stop the agent. Letting go early does nothing. Space or Enter held does the same.
- [NeedsYouInbox](https://creance.pages.dev/docs/NeedsYouInbox.md): Everything blocked on a person, across agents, most urgent first.
- [PermissionLedger](https://creance.pages.dev/docs/PermissionLedger.md): Everything you said "Always allow" to, how often it has been used, and a way to take it back.
- [PlanEditor](https://creance.pages.dev/docs/PlanEditor.md): Reorder, edit, remove and add steps before anything runs. Alt+Up and Alt+Down move a step.
- [QuestionCard](https://creance.pages.dev/docs/QuestionCard.md): When the agent needs information rather than permission.
- [RiskLabel](https://creance.pages.dev/docs/RiskLabel.md): How risky an action is, in words.
- [RunTimeline](https://creance.pages.dev/docs/RunTimeline.md): The run's steps and tool calls. It follows the newest step until you scroll up.
- [StatusBadge](https://creance.pages.dev/docs/StatusBadge.md): A status with a running clock.
- [ToolCallCard](https://creance.pages.dev/docs/ToolCallCard.md): One tool call's whole life: input, result, errors and retries.
- [ToolCallHeader](https://creance.pages.dev/docs/ToolCallHeader.md): Names a tool call and shows its state and attempt.