Getting started and including UI into your application
ui-* packages move to @prepared911/ui. Follow Migrating to @prepared911/ui (including the full @prepared911/ui-calendar parity table). Form-specific notes and the same calendar table live in migrating-from-ui-forms.
Install @prepared911/ui and load its styles once at the app root.
pnpm add @prepared911/ui
Import the aggregate stylesheet once at the app root. It inlines tokens and reset and ships every component and block rule in dependency order.
For animated appearance changes, import @prepared911/ui/appearance-transition.css separately.
Tokens are CSS custom properties. Light values are declared on :where(:root). Dark values are declared under [data-theme='dark'].
Appearance is the data-theme attribute on the document element. There is no theme provider and no brand class on the document.
createAppearancePreference applies light, dark, or the operating system setting. The first application, when the preference is created, does not animate. Later changes animate. Persisting the choice is the app's job. Call dispose() when the owner of the preference goes away.
A subtree that must stay on one appearance uses themeRegionProps from @prepared911/ui. A theme region does not restyle popups portaled outside that subtree.
Import each component from its subpath.
Button is always a <button>. Navigation is Link from @prepared911/ui/link.
A bundle re-exports a group of components from one path. Every component's own subpath keeps working, and a component is in at most one bundle.
| Path | Components |
|---|---|
@prepared911/ui/primitives | Light, everyday parts: layout and type (Box, FlexBox, Grid, Text, Typography, Separator, Scrollable), actions (Button, ButtonGroup, SplitButton, ActionButton, CopyButton, ConfirmMorph, Link), form controls (Field, Fieldset, Form, Label, Input, TextArea, NumberField, Select, Combobox, Checkbox, CheckboxCards, Radio, RadioCards, Switch, Slider, RangeSlider, SegmentedControl, ToggleGroup, Secret, ValueListField, Token), overlays (Dialog, AlertDialog, Drawer, Popover, Tooltip, Menu, ContextMenu, Toast), status (Alert, Banner, Badge, StatusDot, Progress, Loader, LoadingIndicator, Skeleton, PendingValue, EmptyState, EmptyText, Counter, Avatar, Time), and structure (Accordion, Collapsible, Tabs, Breadcrumb, Pagination, Toolbar, Table, DataList, Card, Item, ItemGroup, Icon, Image, Interactable, Portal, OverlayContainerProvider, VisuallyHidden, ErrorBoundary, LoadingBoundary) |
@prepared911/ui/charts | BarChart, LineChart, PieChart, with their tooltip row types |
@prepared911/ui/date-time | Calendar, DateInput, DateTimeInput, DateRangeInput, TimeInput, RecurrenceField |
@prepared911/ui/media | AudioPlayer, VideoPlayer, GeneratedImage |
@prepared911/ui/primitives is about 165 KB brotli, against 394 KB when it held every component. charts adds about 36 KB on top of it, date-time about 56 KB and media about 12 KB.
In a production build, named imports from a bundle tree-shake to the same code as subpath imports. A namespace import (import * as UI from "@prepared911/ui/primitives") keeps the whole bundle, and a dev server loads every module in it.
Module Federation remotes import each component from its own subpath. The shell shares those subpaths, not the bundles, and the build fails when a remote imports a bundle.