# Choosing a component Most wrong choices are between two components that look the same and mean different things. Each table below is one of those families. Find the row that sounds like your situation; the component in it is the answer, and its page opens with the same "Use it for / Not for" so you can check. ## Something to press | The situation | Use | Because | | ----------------------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------- | | The one action the screen is about | [Button](/docs/components/button) `filled` | Once per view. Everything else steps down. | | The other actions beside it | [Button](/docs/components/button) `tonal` / `outlined` / `text` | The emphasis ladder, in that order. | | The action is only an icon | [Icon Button](/docs/components/icon-button) | Same tones, its own geometry, `aria-label` required. | | The screen's main action, floating, on a phone | [FAB](/docs/components/fab) | One per screen. Sits above the content. | | One action plus a menu of alternatives | [Split Button](/docs/components/split-button) | The wide half acts, the narrow half opens the rest. | | A few related actions that read as one control | [Button Group](/docs/components/button-group) | Layout only; the buttons stay plain. | | A list of actions hanging off a trigger | [Menu](/docs/components/menu) | Actions, not values. | | A small action inline with content — "add filter", "assist" | [Chip](/docs/components/chip) | The assist chip. | | Navigation to another page | `Button href`, or a plain link | A link is a link; `variant="link"` inside a sentence. | ## Something to choose | The situation | Use | Because | | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | One of a few options, all visible, mutually exclusive | [Segmented Button](/docs/components/segmented-button) | Two to five options, short labels. | | One of a few options, in a form | [Radio](/docs/components/radio) | The choice is submitted, not applied. | | One of many options | [Select](/docs/components/select) | A styled list of values. | | One of many, and you have to search for it | [Combobox](/docs/components/combobox) | Type to filter; `load` for the server. | | An on/off that takes effect immediately | [Switch](/docs/components/switch) | A setting. Nothing to submit. | | A yes/no that is submitted with the form | [Checkbox](/docs/components/checkbox) | Also "select this row". | | Several of many, above a list | filter [Chips](/docs/components/chip) | The filter bar. | | A number in a range | [Slider](/docs/components/slider) | Precision does not matter; the feel does. | | A colour, a phone number, a price, an emoji | [Color Picker](/docs/components/color-picker), [Phone Input](/docs/components/phone-input), [Price Input](/docs/components/price-input), [Emoji Picker](/docs/components/emoji-picker) | Each one stores the right value and shows the right keyboard. | ## Something to type | The situation | Use | Because | | -------------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------- | | One line | [Text Field](/docs/components/input) | Label, supporting text, affixes, clear, password eye — built in. | | One line with a shape — a slug, a decimal, a card number | [Text Field](/docs/components/input) with `format` | Rejects what does not fit as it is typed. | | A few lines | [Textarea](/docs/components/textarea) | `autosize` for a composer. | | Formatted prose | [Rich Text Editor](/docs/components/rich-text-editor) | A `contenteditable` and a toolbar; nothing heavier. | | Code | [Code Editor](/docs/components/code-editor) | A real textarea with a painted highlight layer, vim optional. | ## Something on top of the page | The situation | Use | Because | | ---------------------------------------------------------- | --------------------------------------------- | ---------------------------------------------------------- | | A decision the person must make before continuing | [Dialog](/docs/components/dialog) | Interrupts. `await dialog.confirm(…)` for the common case. | | A task that keeps the page in view — edit, filter, details | [Sheet](/docs/components/sheet) | A side panel on a laptop, a bottom sheet on a phone. | | A list of actions | [Menu](/docs/components/menu) | Anchored, dismisses on choice. | | A word or two about a control, on hover | [Tooltip](/docs/components/tooltip) | Never for anything the person must read. | | A picture, full screen | [Image Viewer](/docs/components/image-viewer) | Tap to lift it off the page. | | A first-run walkthrough | [Tour](/docs/components/tour) | A spotlight, one thing at a time. | ## Telling the person something | What happened | Show | Because | | -------------------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------- | | Something succeeded or failed, briefly | [Toast](/docs/components/toast) | Never blocks; `toast.promise` follows the request. | | Something about this page, that stays | [Alert](/docs/components/alert) | A banner in the content, with a tone. | | Something is on its way | [Progress](/docs/components/progress) or [Skeleton](/docs/components/skeleton) | A bar when there is a known amount; a skeleton the shape of what is coming. | | There is nothing to show | [Empty](/docs/components/empty) | With the one action that changes that. | | A count, or a status, on something | [Badge](/docs/components/badge) | A pill on its own, or a dot on an icon. | | Something that needs a decision | [Dialog](/docs/components/dialog) | See above. | More on this in [Feedback](/docs/feedback). ## Something to hold content | The situation | Use | Because | | ----------------------------------------- | --------------------------------------- | ---------------------------------------------------------------- | | A unit of content — one order, one metric | [Card](/docs/components/card) | Defaults to `outlined`; a grid of them usually wants `elevated`. | | Rows of one to three lines each | [List](/docs/components/list) | Swipe actions on a phone. | | Rows with columns, sorting, selection | [Table](/docs/components/table) | Server-side paging when it is big. | | Sections that expand one at a time | [Accordion](/docs/components/accordion) | Content in the page, not off it. | | Sections that swap | [Tabs](/docs/components/tabs) | Within a page — not app navigation. | | Panels the person can drag | [Resizable](/docs/components/resizable) | Remembers the layout. | | Media, side by side, swiped | [Carousel](/docs/components/carousel) | Five layouts. | | Photos of different heights | [Masonry](/docs/components/masonry) | The photo wall. | | Cards you drag between columns | [Kanban](/docs/components/kanban) | A board, not a table. | ## Getting around | The situation | Use | Because | | ---------------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------- | | Top-level destinations, on a laptop | [Navigation Drawer](/docs/components/navigation-drawer) | `collapsed` is the rail; `responsive` makes it modal on a phone. | | Top-level destinations, on a phone | [Navigation Bar](/docs/components/navigation-bar) | Three to five, at the bottom. | | The title of this screen and its actions | [Top App Bar](/docs/components/top-app-bar) | Pass `sticky`. | | Where you are, in a hierarchy | [Breadcrumb](/docs/components/breadcrumb) | Collapses in the middle. | | Views within a page | [Tabs](/docs/components/tabs) | Primary on top, secondary nested. | | Pages of a long list | [Pagination](/docs/components/pagination) | Or the Table's own. | | Sections of a long page | [Table of Contents](/docs/components/toc) | The rail on the right of this page. | | Searching the whole app | [Search Bar](/docs/components/search-bar) | The bar and the view it opens into. | ## Showing data | The situation | Use | Because | | ----------------------------- | ------------------------------------------------ | --------------------------------------- | | A number over time | Line or Area [Chart](/docs/components/chart) | Time goes on the x axis. | | Numbers by category | Bar [Chart](/docs/components/chart) | Categories are bars. | | One number against its range | [Gauge](/docs/components/gauge) | The dial. | | A trend inside a stat | Sparkline, from [Charts](/docs/components/chart) | No axes; the shape is the point. | | Places | [Map](/docs/components/map) | `omaris/map`, opt-in. | | Code, read-only | [Code Block](/docs/components/code-block) | Highlighted, copyable. | | A change between two versions | [Diff Viewer](/docs/components/diff-viewer) | Unified or split. | | A JSON payload | [JSON Viewer](/docs/components/json-viewer) | Collapsible and searchable. | | A stream of log lines | [Log Viewer](/docs/components/log-viewer) | Levels, ANSI colour, follow. | | Any string on the screen | [Text](/docs/components/text) | The variant is the whole type decision. | > **Note** Every component page opens with "Use it for" and "Not for", and every > "Not for" line names the component to use instead. When a table above does > not settle it, that section will.