CynosureComponents
Components
116 components and foundations, grouped by what they are for.
Foundations
10ButtonBaseThe native <button> for Cynosure, and the only module allowed to render one. It is a foundation: thin, unstyled, and meant to be built on by components rather than used in product code.
LinkBaseThe native <a> for Cynosure, and the only module allowed to render one. It is a foundation: it adds safe link behaviour and no styling.
InputBaseThe native text-like <input> for Cynosure, and the only module allowed to render one. It is a foundation: no visual opinions, so composites style it.
FileInputBaseThe native <input type="file"> for Cynosure, and the only module allowed to render one. It is a foundation: no visual opinions, so composites style or hide it.
TextAreaBaseThe native <textarea> for Cynosure, and the only module allowed to render one. It is a foundation: no visual opinions, so composites style it.
ChoiceBaseA native checkbox or radio, visually hidden under a Cynosure skin but still focusable, clickable and form-associated. It is a foundation: it has no visual opinions, and the composite that uses it draws the visible control.
HiddenValueLets a custom widget take part in a native form. It renders a visually and semantically hidden input that carries the widget's value, so the form sees it like any other field. It is a foundation: it has no visual output.
LiveRegionA hidden live region for screen reader announcements that belong to one component: "Copied", "Moved to position 3 of 8", "Zoom 150%", "3 of 12". It is a foundation: it has no visual output. For announcements from anywhere in an app, use Announcer and useAnnounce(), which speak through LiveRegions near the root.
DialogBaseThe native <dialog> for Cynosure, and the only module allowed to render one. It is a foundation: thin, unstyled, and meant to be built on by components rather than used in product code.
IconRenders a Facet icon as inline SVG. It is a foundation, and the one that has visual opinions: stroke only, currentColor, sized and toned through tokens.
Controls
29ButtonTriggers an action: save, export, delete, open. One Button is one action. If clicking it takes the user somewhere, use Link instead.
IconButtonA square Button with only an icon. It needs a label, which is both its accessible name and its tooltip.
CopyButtonAn icon button that copies a value to the clipboard. It turns into a check for a moment and announces "Copied"; if the clipboard refuses, it shows an error instead and still never throws.
LinkAn inline text link that takes the user somewhere. For an action that doesn't navigate, use Button.
TextFieldSingle-line text input with a label, description, error, optional icons and an optional clear button. For several lines use TextArea; for search use SearchField.
NumberFieldA field for numbers. People type in their own format or step the value with the keyboard or the − and + buttons; your code gets a number.
SearchFieldA TextField preset for search: it has a search icon, is clearable, and submits on Enter. For a plain text input, use TextField.
TextAreaMulti-line text input. It starts at rows, grows with its content up to maxRows, then scrolls. For a single line, use TextField.
SelectPicks one option from a list that opens on demand. The trigger is a Cynosure button and the list opens in the top layer, so it is never clipped. For a short list that should stay visible, use RadioGroup.
ComboboxA text input with a list of suggestions. People type to narrow the list, then pick with the arrow keys and Enter or with a click. Options can come from a server as they type.
TagInputA field for several short values: topics, labels, keywords, recipients. People type and press Enter, pick a suggestion or paste a list, and remove tags with a click or the keyboard.
CheckboxA checkbox with a label, for choices that are independent of each other. It is a native input under a drawn box, so forms, reset and keyboard work as the browser does them. For a setting that takes effect immediately, use Switch.
SwitchAn on/off setting that takes effect straight away, such as "Auto-expand". It is built on a native checkbox with role="switch". If the choice is confirmed later with a submit button, use Checkbox.
RadioGroupPicks one option from a short list, with every option visible. It is built on native radios, so forms, reset and required work without extra code. For a compact switcher use SegmentedControl instead.
SegmentedControlA compact single choice for view switchers and modes, such as Tree or Raw. Segments sit side by side and exactly one is active. For a longer list of options use RadioGroup or Select.
SliderPicks a number by dragging a thumb along a track, or a range with two thumbs. It works with the keyboard, pointer and touch, and submits with native forms.
DateFieldA date in a form: typed, stepped with the arrows, or picked from a calendar.
TimeFieldA time of day in a form: typed loosely, or with picker chosen from columns that roll under a lens, and reported as 24-hour HH:MM.
ChecklistA list of rows people add, tick, rename and remove, such as a task's subtasks. If people only choose among options you wrote, use Checkbox instead.
PaginationMoves between the pages of a list or table: previous and next, numbered pages, and the current page marked. It is a navigation landmark built from Button and IconButton.
ColorFieldA colour input that takes any CSS colour as text, or lets people pick one from a saturation area, a hue slider, an opacity slider and, where the browser allows, the screen itself.
ColorSwatchesA palette of colours to choose from: brand colours, presets or recent colours.
KeyValueEditorEditable key and value pairs, such as HTTP headers or environment variables, in rows or as text.
FileDropA place to add files: drop them on it, or press its button to pick them. It checks each file and explains what it turned away.
PathFieldA file or folder path: a text field with a Browse button inside its end that asks your app's picker for a path, and a clear button. The path can also be typed. It is for apps with their own file dialog (Electron), where a browser file input gives no path.
SignaturePadA pad to draw a signature with a mouse, finger or pen.
SelectionFrameMove, resize and rotate one selected object with a mouse, pen, finger or the keyboard.
CompareSliderTwo versions of the same thing, one over the other, split by a divider people move to compare them.
ThemeToggleA light, dark or system switch with sun, moon and monitor icons. It is a SegmentedControl wired to useColorMode. Pair it with CynosureTheme so the chosen mode is applied.
Structure
26AppShellThe frame of an app: a top bar, the navigation beside the content, and the main region. When there is not enough room, the navigation moves into a drawer opened from a menu button.
TitleBarThe title bar of an installed app that draws its own: a frameless Electron window, or an installed web app using Window Controls Overlay. The whole bar drags the window, every control inside stays clickable, and the app's window controls sit at its end.
StatusBarThe bar along the bottom of a desktop app or editor: short status segments (connection, branch, cursor position, problems) in a start and an end cluster. Segments that do something are buttons, and one can open a Popover above itself.
ContainerThe page column. It centres its content, caps how wide it gets and adds side gutters, so every page of an app lines up. It is layout only: no background, border or text styles.
PageHeaderThe top of a page or a major section: where you are (breadcrumbs or an eyebrow), what this is (the title), one or two sentences about it (the lead), and the page's actions. For the heading of a smaller block inside a page, use Heading on its own.
StackLays children out in a column with a gap from the space scale. For a row, use Inline.
InlineLays children out in a row with a gap from the space scale. For a column, use Stack; Inline is a Stack in a row, with its items centred and an optional wrap.
GridLays items out in rows and columns: a fixed number of equal columns, a number per width of the grid, or as many as fit at a minimum width. Gaps and padding are space tokens.
ScrollAreaA box that fills its parent and scrolls what does not fit. It can follow the end while content arrives and hold an overlay, such as a "3 new" pill, that stays put while the content scrolls.
DividerA line that separates content: between sections of a page or card, or between items in a row. It can carry a short label such as "or". If the content only needs space between it, use the gap of Stack or Inline and no line.
AspectRatioA box that keeps a width-to-height ratio at any width, for an image, a video, a map, a chart or an embed. For a picture that also needs a loading placeholder and an error fallback, use Image instead.
BreadcrumbsShows the trail from the top of a site or app to the current page. Every item but the last is a link back up the trail; the last one is the page being shown. For moving between sections of an app, use SideNav instead.
SideNavVertical navigation for an app or a docs site: links in titled sections, groups that expand, the current page marked, and a collapsed icon rail.
SplitPaneTwo panes with a divider people can move, by dragging it or with the keyboard.
CardA content container. Give it href or onClick and the whole card becomes one link or one button. For a plain grouping with no surface, use Stack.
ToolbarGroups related controls into one named bar with a single Tab stop, following the WAI-ARIA toolbar pattern. Arrow keys move between the controls. For one standalone action, use Button.
TabsSwitches between views of the same thing, such as a document's tree, raw and schema views, while staying on one page. If the options filter or change a value rather than swapping whole panels, use SegmentedControl.
DisclosureShows and hides one section behind a button: advanced options, extra detail, a long explanation. For several related sections that share state, use Accordion.
AccordionA stack of collapsible sections that share state: one open at a time, or any number. Each section is a Disclosure.
TreeA hierarchical list people can open, close and select from: folders and files, a JSON or DOM tree, nested settings. It follows the WAI-ARIA tree view pattern, loads children on demand and can render hundreds of thousands of rows.
SortableListA list people put in order, by dragging a row's handle or with the keyboard.
VirtualListA list of thousands of rows that stays fast: only the rows in view are rendered.
CalendarA month of days to pick one from, or to lay out a month's plans on.
DocumentViewportA scrolling, zoomable document of pages, rendering only the pages near the view.
PanZoomCanvasA surface to pan and zoom freely, for diagrams, maps and boards; your content, placed in canvas units.
ZoomControlsZoom out, the current percent with a menu of choices, and zoom in.
Overlays
12TooltipShort supplementary text for a control, shown on hover or keyboard focus. It becomes the trigger's accessible description. For an icon-only button, IconButton already shows its label as a tooltip.
HoverCardA passive preview beside its anchor, such as a larger thumbnail of the page under the pointer.
PopoverA small floating panel attached to a button, for options and details that belong to that button: filters, view settings, a quick form. It sits in the browser's top layer, so no parent can clip it.
FloatingToolbarA compact toolbar beside the box or text it works on, like the mini toolbars of document editors. On phones, DockedToolbar puts the same controls in one row above the on-screen keyboard.
MenuA button that opens a list of commands: edit, copy, export, delete. Choosing one runs it and closes the menu. For picking a value that stays shown on the control, use Select.
MenubarA desktop application's menu bar: a row of titles (File, Edit, View), each opening a Menu of commands. Once one menu is open, the arrow keys and the pointer move straight between menus, as in a native app.
ContextMenuA menu of commands for one thing, opened where the person points: right-click with a mouse, a long press on a touch screen, or Shift+F10 on the keyboard.
DialogA modal window over the page for a task the person must finish or cancel before going on: confirm a destructive action, fill in a short form. The page behind is inert until it closes. In a narrow container (a phone, an extension popup) it becomes a bottom sheet.
ProgressOverlayA modal progress dialog for long work the page has to wait for.
SheetA Dialog docked to an edge of the screen: a drawer from the bottom, or a full-height panel at the inline end. It behaves exactly like a Dialog (focus, Escape, backdrop, labels) and slides in from its side.
CommandPaletteA search box over every command in the product. Press Ctrl+K (Command+K on a Mac), type a few letters, press Enter. It is the fastest way to reach an action without hunting through menus.
ToastA short message about something that just happened, shown along one edge of the screen and gone after a few seconds: "Saved", "Copied", "Upload failed". It never takes focus and never blocks the page.
Feedback and display
22NoticeAn inline message about part of the page: a status, a warning or an error that stays in place until it is resolved or the person dismisses it.
EmptyStateWhat to show where content will be: no items yet, no search results, nothing selected. It says what is missing and offers the next step.
ErrorBoundaryCatches errors thrown while its children render and shows a fallback in their place, so one crashing part of the app leaves the rest working. The user can try again, and moving on (a new resetKey) recovers by itself.
ProgressBarShows how far a task has got: an upload, an export, the steps of a setup. When the amount is unknown it shows a moving segment instead.
StepsShows progress through an ordered flow, such as a setup wizard or a checkout: numbered steps, finished ones ticked, the current one marked.
LoadingDotsThree dots that pulse in sequence, or a turning spinner, for short waits of unknown length. For a task with known progress, show the progress itself.
SkeletonA placeholder in the shape of content that is still loading: lines of text, a block or an avatar circle. It holds the space the content will take, so the layout does not jump when it arrives.
DescriptionListShows term and detail pairs, such as the facts about a record or a summary of settings. Terms sit beside their details when there is room and above them when the list is narrow.
StatA figure with its label, a KPI tile: the value with an optional unit, the change since last time and a line of context, on a Card. With href the whole tile is one link to the figure's detail. For several facts about one record, use DescriptionList instead.
ListA real list (ul or ol) with drawn markers: bullets, numbered how-to steps, a ticked feature list, or an icon per item. Each item has a label and an optional description under it. For long-form text with lists inside, use Prose; for progress through a flow, use Steps.
TableRows of data with headers. Columns can sort, rows can be selected, and the header can stay in view while the body scrolls.
TextOne piece of text in Cynosure's type scale: a label, a caption, a lead paragraph, a helper line or a value. For long-form content use Prose; for a title use Heading.
HeadingA section or page heading. level sets the element (h1 to h6) and size sets how it looks, so the page outline stays correct whatever the design asks for. For text that is not a heading, use Text.
ProseGives long-form HTML that you do not style element by element (rendered Markdown, release notes, help pages) Cynosure's typography: headings, paragraphs, lists, links, quotes, code, tables and images.
AvatarA person, team or thing shown as a picture, falling back to initials and then to an icon. AvatarGroup overlaps several and sums up the rest as "+3". An avatar only shows who it is; to make one pressable, put it inside a Button or Link.
IconTileA Facet icon on a tinted square or circle: the mark of a feature, a settings section, a stat or a list item. It is decorative unless you give it a label. For a person or a team use Avatar; for an icon inside a line of text use Icon.
ImageA picture that never shifts the layout, shows a placeholder while it loads and something sensible when it fails. For a person or an account, use Avatar; for an interface symbol, use Icon.
CodeBlockShows code to read and copy, with a header naming the file or language and a copy button.
AnnouncerTells screen reader users about changes that happen without moving focus, such as "Draft saved" or "12 results". <Announcer> renders two hidden live regions inside your app; useAnnounce() speaks through the nearest one.
BadgeA small status or category label in the mono "eyebrow" style. It only labels; it does nothing when clicked. For an action use Button.
KbdA keyboard shortcut shown as drawn key caps. Screen readers get a spoken combination instead ("Control plus K").
FieldAdds a label, help text and an error message to any control and wires them together for assistive tech. Your control is rendered through a render prop that receives the ids and state. Checkbox and Switch carry their own label, so they don't need Field.
More
17ChatMessageOne message in an assistant chat: the person's at the end, filled with the accent; the assistant's at the start, after its avatar. It holds any content (render markdown into Prose yourself), shows a caret while text streams in, and offers actions such as copy and retry.
ChoiceThe row a choice control sits in: the control, its label and an optional description, the whole row clickable. Checkbox, Switch and each RadioGroup option are Choice rows that draw their own control.
DataGridA read-only grid for large results: only the rows and columns in view are rendered, so a hundred thousand rows by fifty columns scroll and move focus as quickly as twenty.
DeviceFrameA phone, tablet or browser window drawn in CSS around a screenshot, a video or a live demo. The screen keeps its ratio at any width and clips its content to its rounded corners.
HighlightedTextText with the parts that matched a search marked: the characters a fuzzy matcher returned, or every occurrence of a query. Tree, Combobox and CommandPalette mark their matches with it.
HotkeyFieldRecords a keyboard shortcut for a keybindings page. It shows the shortcut as key caps beside a record toggle and a clear button; while recording, it takes the next chord itself, so the app's own shortcuts do not fire, and writes it the way useHotkey reads it ("mod+shift+p"; see CommandPalette for useHotkey).
ListRowInteractive rows for an app's lists (notifications, an activity feed, saved queries, query history, connections): a leading slot, a title with up to two quieter lines, a trailing slot, and actions shown on hover or focus. ListRows is the list that holds them and gives it one Tab stop and arrow keys.
OptionListThe drop-down list of options under a field: options with an optional icon and description, group headings, and a note when there is nothing to choose. Select, Combobox and TagInput draw their lists with it. It is a building block: for a ready field, use one of those.
OverlayFrameA frame whose content fills it, with an overlay pinned at the bottom centre that stays put while the content scrolls under it: a "3 new" pill, a "jump to latest" button.
QRCodeA QR code drawn as one crisp SVG path, so a phone can open a link shown on a bigger screen. It stays dark on light in every colour mode, because many phone cameras cannot read an inverted code.
RowActionsThe buttons at the end of a row: out of the way until the row is pointed at or holds focus, always shown on touch screens, and in the Tab order only on the row that holds the Tab stop. ListRow, Tree and ChatMessage draw their actions with it; use it for a row of your own.
SectionA full-width band of a page: a background, space above and below, and the content in the page column. Stack Sections to build a landing or documentation page that scrolls as a document.
SiteFooterThe bottom of a website: the brand and a tagline, columns of links under headings, and a bottom row for the copyright, legal links and social links. It stacks on narrow screens.
SiteHeaderThe top bar of a website that scrolls as a document: a skip link, the brand, the site navigation and actions. It sticks to the top of the window, and on narrow screens the navigation moves into a menu sheet.
SkipLink"Skip to content": the first stop of a page's Tab order. It is hidden until it has focus, then shown at the top-start corner of the window as an accent outline Button. It is a real link, so it works without JavaScript; with it, focus also moves to the target.
SortButtonThe button in a sortable column's header: the header text and an icon that shows the sort. Table and DataGrid render it for their sortable columns.
VisuallyHiddenContent for screen readers only: out of sight, still in the accessibility tree and read in place. With focusable, it is shown while something inside it has keyboard focus.