# @umriss-ui/core

> React component library for data-dense dashboards and tools - forms, date pickers, overlays, a tree view and a command palette. Precise, quiet, professional.

Version 0.29.0. Install with `npm install @umriss-ui/core`. Each link below leads to that page as Markdown. Every page below in full - its examples' source, its props tables generated from the code, and what it deliberately does not do - stands in one file: [llms-full.txt](https://romanhaendler.github.io/umriss-ui/core/llms-full.txt). The npm package carries the same text for the installed version as `docs/llms-full.md`; prefer that one when the package is installed.

## Scenarios

Composed, realistic screens built from the package.

- [Resolve an incident](https://romanhaendler.github.io/umriss-ui/core/index.md): The engineer on call at Quillmere works an open incident from this console: check the service has recovered, clear its alerts, and close it with a summary.
- [Dispatch a tour](https://romanhaendler.github.io/umriss-ui/core/index.md): A dispatcher at Ferrow Parcel puts together an afternoon tour for the parcels that could not be delivered this morning, and sends it out.
- [Approve spending against a budget](https://romanhaendler.github.io/umriss-ui/core/index.md): The finance controller at Carrow & Lisle signs off incoming invoices, each read against what its cost centre has left for the quarter.
- [Set up a team](https://romanhaendler.github.io/umriss-ui/core/index.md): A team lead at Tidewell keeps the team's settings here: who is in it and for how many hours, how sprints run, and who hears about what.
- [Watch a kiln line over a shift](https://romanhaendler.github.io/umriss-ui/core/index.md): A line lead at Brenholt Tile Works keeps this control room open through the shift to see the kiln, its alarms, the plan and the OEE at once.

## Getting started

What an application sets up once, before the first component.

- [Installation](https://romanhaendler.github.io/umriss-ui/core/installation.md): What an application does once before its first component: install the package, choose the fonts and let light and dark follow the page. The styles load themselves, and no provider is needed.
- [UmrissProvider](https://romanhaendler.github.io/umriss-ui/core/umrissprovider.md): Sets once, at the root, what an application shares: the density of its tables, where overlays open, how long toasts stay and where they stand, and the language. It is optional; every component works the same without it.

## Customising

What every component shares and an application sets once: its colours, its size, its words.

- [Theming](https://romanhaendler.github.io/umriss-ui/core/theming.md): Make the components look like your product (theme, colours, dark mode, CSS variables). Every colour, size, shadow and duration they draw with is a token, a `--u-…` custom property, and the tokens are the whole styling API: override one with ordinary CSS, for the application or for one region. The table lists each with its light and dark value.
- [Sizes](https://romanhaendler.github.io/umriss-ui/core/sizes.md): How wide and how tall a field is (width, height, field size). A field fills its place, holds still in a row whatever it shows, takes the width of its value with `chars`, and takes one size from the place it stands in.
- [Language](https://romanhaendler.github.io/umriss-ui/core/language.md): The words and the number and date notation the components write themselves: English by default, German in one import, and any single entry your own. Wording is a directory of named entries, not a translation call (also called i18n or localisation).

## Layout

How a screen's parts are arranged, grouped and given room.

- [Stack and Grid](https://romanhaendler.github.io/umriss-ui/core/stack-and-grid.md): Lay a screen's parts out in a column, a row or a grid, spaced by the library's spacing steps instead of pixel numbers (flex and grid layout). Reach for them before a wrapper with margins of its own.
- [Divider](https://romanhaendler.github.io/umriss-ui/core/divider.md): A line between two groups of content, across or upright, that may name the part after it (also called a separator or rule).
- [Card](https://romanhaendler.github.io/umriss-ui/core/card.md): A surface that holds one block of a screen together: a head with its title and actions, and a body (also called a panel or tile). Reach for it for each block of a dashboard or a detail view.
- [Splitter](https://romanhaendler.github.io/umriss-ui/core/splitter.md): Two panes with a draggable line between them (also called a split view or resizable panes). Use it when the user needs both at once and decides how much of each: a list beside its detail, a chart above its alerts.
- [Dock](https://romanhaendler.github.io/umriss-ui/core/dock.md): A strip of tools that floats above one surface, a chart or a map, and rests at the edge the user moves it to (also called a floating toolbar). Reach for it when the tools act on that surface and must not take room from it.

## Typography

The type a screen is set in.

- [Typography](https://romanhaendler.github.io/umriss-ui/core/typography.md): Sets paragraphs, headings and links on the library's type scale, so a screen of your own reads like the components around it. Reach for it wherever you would otherwise style text by hand.
- [VisuallyHidden](https://romanhaendler.github.io/umriss-ui/core/visuallyhidden.md): Text a screen reader announces but the eye does not see (also called screen-reader-only or sr-only). Reach for it when a visible label is clear from its surroundings but not on its own, and for a skip link.

## Actions

What a user presses when something is to happen.

- [Button](https://romanhaendler.github.io/umriss-ui/core/button.md): Starts one action when pressed: save, send, deploy, delete. Its variant says how much weight the action carries beside its neighbours, and while the action runs it shows that it is busy and cannot be pressed twice.
- [IconButton](https://romanhaendler.github.io/umriss-ui/core/iconbutton.md): A square button that shows only an icon (also called an icon-only button): refresh, export, close, the actions of a row. Reach for it where the icon is known well enough to stand alone; its name is required and shows as a tooltip.
- [ButtonGroup](https://romanhaendler.github.io/umriss-ui/core/buttongroup.md): Joins buttons that act on the same thing into one control. Its companion SplitButton runs one main action and keeps the rarer variants in a menu beside it (also called a dropdown or menu button).

## Forms

Where a user types a value or sets one directly on the screen.

- [Input](https://romanhaendler.github.io/umriss-ui/core/input.md): A single line of text (text field, text box): names, references, addresses, search terms. Reach for it whenever the answer is short free text; for numbers take a [NumberInput](#/numberinput).
- [FormField](https://romanhaendler.github.io/umriss-ui/core/formfield.md): The frame around a field: its label, a hint below it and the error that replaces the hint. Wrap every field in one, so the question, the help and the problem are read out together.
- [Textarea](https://romanhaendler.github.io/umriss-ui/core/textarea.md): Text over several lines (multi-line text field): a comment, a summary, a note to the driver. It can grow with its text and count the characters left.
- [NumberInput](https://romanhaendler.github.io/umriss-ui/core/numberinput.md): A number typed exactly (numeric field, spin box): an amount, a weight, hours. It shows the unit inside the field, keeps the value in its range and steps with the arrow keys.
- [Slider](https://romanhaendler.github.io/umriss-ui/core/slider.md): A value set roughly between two bounds (range slider): a share of traffic, an alert threshold, weekly hours. The position on the track says as much as the figure.
- [Checkbox](https://romanhaendler.github.io/umriss-ui/core/checkbox.md): A yes or no that counts when the form is saved (tick box). It also shows the mixed state of a parent whose children are partly checked.
- [Switch](https://romanhaendler.github.io/umriss-ui/core/switch.md): On or off, taking effect at once (toggle): paging at night, autoscaling, a feature for one service. A screen reader announces it as a switch, on or off.
- [RadioGroup](https://romanhaendler.github.io/umriss-ui/core/radiogroup.md): One choice out of a few that all stay in view (radio buttons, option group). Each option may carry a sentence that explains it.
- [SegmentedControl](https://romanhaendler.github.io/umriss-ui/core/segmentedcontrol.md): One choice out of a few short possibilities, drawn as one control with a segment for each (segmented button, button toggle): a sunken track, the choice lifted out of it. As tall as a select, so it stands in a row of fields too.
- [FileInput](https://romanhaendler.github.io/umriss-ui/core/fileinput.md): Choose files from the system's dialog or drop them on the zone (file picker, upload field). The chosen files are listed with their size and can be removed one by one.

## Choosing

Where a user chooses one value or several from a list that opens.

- [Select](https://romanhaendler.github.io/umriss-ui/core/select.md): One choice from a short, known list (dropdown). Under a mouse and the keys it opens the Combobox's list; under a finger the system's picker, a wheel on the phone.
- [Combobox](https://romanhaendler.github.io/umriss-ui/core/combobox.md): One choice from a long list, found by typing (autocomplete, typeahead, searchable select): a driver, a service, an account. The list filters along while the value stays exactly one.
- [MultiSelect](https://romanhaendler.github.io/umriss-ui/core/multiselect.md): Several values from a list (multi-select, tag picker): a project team, services to filter by. The chosen ones stand as chips in the field, with a view in the panel that shows only them.

## Dates and times

Where a user picks a day, a moment or a span of them from a calendar that opens.

- [DatePicker](https://romanhaendler.github.io/umriss-ui/core/datepicker.md): One day, picked in a calendar (date field): a delivery date, a due date. Weeks begin on Monday.
- [DateTimePicker](https://romanhaendler.github.io/umriss-ui/core/datetimepicker.md): One moment, day and time of day in one field (date-time field): when an incident began, when an alert fired.
- [DateRangePicker](https://romanhaendler.github.io/umriss-ui/core/daterangepicker.md): A span of days, from one day to another (date range): leave, a sprint, a reporting period. Two months side by side, presets for the usual spans, and the days counted while the pointer moves.
- [DateTimeRangePicker](https://romanhaendler.github.io/umriss-ui/core/datetimerangepicker.md): A span with a time at each end (date-time range): a planned downtime, a release freeze, the minutes an objective was breached. The footer shows the duration while it is set.

## Feedback

What tells a user how things stand and that something is under way.

- [Spinner](https://romanhaendler.github.io/umriss-ui/core/spinner.md): A turning circle that says something is running, without saying how far (also called a loading indicator). Reach for it for short waits whose length nobody knows, beside a word that says what runs.
- [ProgressBar](https://romanhaendler.github.io/umriss-ui/core/progressbar.md): A bar that shows how far a job has come, or that it runs while nobody knows how far (also called a progress indicator). Reach for it for imports, uploads and anything else that counts towards an end.
- [Skeleton](https://romanhaendler.github.io/umriss-ui/core/skeleton.md): Grey shapes that stand where content is still loading and hold the height it will have (also called a placeholder or shimmer). Reach for it when you know the layout of what is coming, so nothing jumps when it arrives.
- [Alert](https://romanhaendler.github.io/umriss-ui/core/alert.md): A message that stays in the page until its matter is settled (also called a banner or callout). Reach for it when the reader must notice something here: a failed import, an approval waiting, a form that did not save.
- [Toast](https://romanhaendler.github.io/umriss-ui/core/toast.md): Short feedback in the corner of the window that interrupts nothing and goes away by itself (also called a snackbar or notification). Reach for it to confirm what has just happened: saved, exported, approved.
- [EmptyState](https://romanhaendler.github.io/umriss-ui/core/emptystate.md): What stands where a list or panel has nothing to show: what is missing, why, and the way forward (also called a blank slate). Reach for it for a first use, a filter that found nothing, or a queue that is clear.

## Overlays

What opens above the screen and closes again.

- [Tooltip](https://romanhaendler.github.io/umriss-ui/core/tooltip.md): A sentence of explanation that appears while the pointer rests on an element or the keyboard focus is on it (also called a hint). Reach for it to explain an abbreviation or a control; an icon button names itself as an [IconButton](#/iconbutton).
- [Popover](https://romanhaendler.github.io/umriss-ui/core/popover.md): A surface that hangs from a trigger and closes on Escape, an outside click or scrolling (also called a popup, flyout or dropdown panel). Reach for it for a small panel of your own: a filter, a detail, a short form.
- [Menu](https://romanhaendler.github.io/umriss-ui/core/menu.md): A list of actions that opens under a button (also called a dropdown menu). Reach for it when a place has more actions than room for buttons, or for the actions of each row in a list.
- [ContextMenu](https://romanhaendler.github.io/umriss-ui/core/contextmenu.md): A menu that opens at a point, for a right-click on something that is not a button: a row, a canvas, a bar in a schedule (also called a right-click menu). The entries and the keyboard are those of the menu.
- [Modal](https://romanhaendler.github.io/umriss-ui/core/modal.md): A window above the page that holds the focus until it is answered or closed (also called a dialog). Reach for it for a short task that interrupts the page: create an item, edit its settings, read a policy.
- [Drawer](https://romanhaendler.github.io/umriss-ui/core/drawer.md): A modal window that slides in from the left or right edge of the screen (also called a side sheet or side panel). Reach for it for the detail of something picked from a list, while the list stays in sight behind it.
- [ConfirmDialog](https://romanhaendler.github.io/umriss-ui/core/confirmdialog.md): A small modal window with one question and two buttons, for the moment before something that cannot be undone (also called a confirmation). Reach for it before deleting, rejecting or closing for good.
- [CommandPalette](https://romanhaendler.github.io/umriss-ui/core/commandpalette.md): A search field above the page that finds commands and places as you type (also called a command menu or quick switcher). Reach for it when an application has more actions and pages than any menu can show.

## Navigation

How a user finds their way through a screen and between screens.

- [Breadcrumb](https://romanhaendler.github.io/umriss-ui/core/breadcrumb.md): Shows where the current page sits in a hierarchy and leads back up to any level above it (also called a trail or path). Where the trail runs out of room, its middle levels fold into a menu.
- [Tabs](https://romanhaendler.github.io/umriss-ui/core/tabs.md): Several views of one thing in one place, exactly one of them visible (also called a tab bar). Reach for tabs when the views are alternatives the user switches between, not content to compare side by side.
- [Accordion](https://romanhaendler.github.io/umriss-ui/core/accordion.md): Long content in sections behind headers the user opens one or several at a time (also called collapsible sections or a disclosure). Reach for it where a reader needs a few of many sections, such as settings, a runbook or a report.
- [Stepper](https://romanhaendler.github.io/umriss-ui/core/stepper.md): Shows how far a procedure has come: which steps are done, which one is being worked on, which lie ahead and which failed (also called a progress tracker). Reach for it for approvals, rollouts and closing routines.
- [TreeView](https://romanhaendler.github.io/umriss-ui/core/treeview.md): A hierarchy the user expands, walks with the keys and optionally ticks (also called a tree or outline). Reach for it for folders, teams and cost-centre structures; large trees stay quick because only the visible rows are drawn.

## Data display

Single values and labels, read at a glance.

- [Badge](https://romanhaendler.github.io/umriss-ui/core/badge.md): A small word or number at the edge of something else: a status, a count (also called a label or chip). Reach for it to mark the state of a row, or how many items wait behind a button.
- [Tag](https://romanhaendler.github.io/umriss-ui/core/tag.md): A short label on content that the user can remove where you allow it (also called a chip). Reach for it for active filters, chosen values and assignments.
- [Stat](https://romanhaendler.github.io/umriss-ui/core/stat.md): A single figure with its verdict: read against limits, with the history before it, the deviation from its target and how fresh it is (also called a KPI tile or metric card). Reach for it for the few numbers a screen is watched for.
- [Meter](https://romanhaendler.github.io/umriss-ui/core/meter.md): A bar that shows a measured share, such as capacity booked or budget used, coloured by your verdict on it (also called a gauge bar or level indicator). Reach for it in lists and tables where a percentage alone is hard to compare.
- [Sparkline](https://romanhaendler.github.io/umriss-ui/core/sparkline.md): A small line of a history, at the height of a line of text, without axes or labels (also called a micro chart). Reach for it beside a value or in a table cell, where the shape of the last hours tells more than the figure alone.

## API index

Every name the package exports, in one place.

- [API index](https://romanhaendler.github.io/umriss-ui/core/api.md): Everything `@umriss-ui/core` exports, with its signature. A component's props stand on its own page.