# Which component when

Maps a task to a Koobiq component and names the neighbor it is confused with, and why. Find the words of the request in the first table, open the cluster they lead to, then the Markdown of the component it names.

## Clusters

| Words in the request | Cluster |
| - | - |
| multiselect, multiple, chips, tokens, 500 options, long list, virtual scroll | [Pick a value from a set](https://koobiq.io/which-component-when/pick-a-value-from-a-set.md) |
| search field, suggest, type-ahead, dictionary, free value | [Pick a value from a set](https://koobiq.io/which-component-when/pick-a-value-from-a-set.md) |
| on/off, switch, instant setting, checkbox group, partially selected | [Pick a value from a set](https://koobiq.io/which-component-when/pick-a-value-from-a-set.md) |
| loading, spinner, percent, remaining time, placeholder, skeleton, busy block | [Show that something is in progress](https://koobiq.io/which-component-when/show-that-something-is-in-progress.md) |
| error, warning, success, acknowledge, confirm, "are you sure", notify, missed message, history of messages | [Tell the user something](https://koobiq.io/which-component-when/tell-the-user-something.md) |
| empty, no data, no results, nothing found, failed to load | [Tell the user something](https://koobiq.io/which-component-when/tell-the-user-something.md) |
| dialog, window, drawer, panel, preview, blocks the page, stacking | [An extra layer over the page](https://koobiq.io/which-component-when/an-extra-layer-over-the-page.md) |
| hint, hover, truncated, ellipsis, three dots, "show more", collapse, fit the width | [Text that does not fit](https://koobiq.io/which-component-when/text-that-does-not-fit.md) |
| table, grid, sort, resize columns, key-value, attributes, filters, highlight matches | [Tabular and structured data](https://koobiq.io/which-component-when/tabular-and-structured-data.md) |
| menu, main navigation, toolbar, breadcrumbs, tabs, sections, switch view, another app | [Navigation](https://koobiq.io/which-component-when/navigation.md) |
| edit in place, pencil, save immediately, form, date, time, period, timezone, upload | [Editing existing data](https://koobiq.io/which-component-when/editing-existing-data.md) |
| label, status, count, country, avatar, user, clickable icon | [Labels, marks, identity](https://koobiq.io/which-component-when/labels-marks-identity.md) |

## Components

One line per component: when to use it. `→` names the neighbor to prefer in the case after it.

### Choosing values

- [`select`](https://koobiq.io/en/components/select.md) — one or more values from a list the application owns; search past 10 options, virtual scroll for long lists. → [`autocomplete`](https://koobiq.io/en/components/autocomplete.md) when the value is typed, [`tree-select`](https://koobiq.io/en/components/tree-select.md) when the data is a hierarchy.
- [`tree-select`](https://koobiq.io/en/components/tree-select.md) — one or more values from hierarchical data, with the tree kept visible while searching.
- [`autocomplete`](https://koobiq.io/en/components/autocomplete.md) — a text field that suggests matches while typing, including server-driven suggestions; single value.
- [`tag-autocomplete`](https://koobiq.io/en/components/tag-autocomplete.md) — several values from a dictionary, with custom values allowed; the dropdown is an autocomplete panel.
- [`tag-input`](https://koobiq.io/en/components/tag-input.md) — several free-form values entered as tags.
- [`tag-list`](https://koobiq.io/en/components/tag-list.md) — a set of tags with keyboard navigation, selection and removal; no entry of its own.
- [`tag`](https://koobiq.io/en/components/tag.md) — one token inside an input control. → [`badge`](https://koobiq.io/en/components/badge.md) for a standalone label.
- [`list`](https://koobiq.io/en/components/list.md) — related items as page content, single or multiple (`multiple="checkbox"` when the state must be visible at a glance); virtual scroll for long lists, but not together with dragging.
- [`tree`](https://koobiq.io/en/components/tree.md) — hundreds of items the user navigates as a catalog. → [`list`](https://koobiq.io/en/components/list.md) without hierarchy or volume.
- [`radio`](https://koobiq.io/en/components/radio.md) — up to ~7 mutually exclusive options, all visible.
- [`checkbox`](https://koobiq.io/en/components/checkbox.md) — independent options, and the group state via `indeterminate`.
- [`toggle`](https://koobiq.io/en/components/toggle.md) — a binary setting that applies immediately, with no Save.
- [`button-toggle`](https://koobiq.io/en/components/button-toggle.md) — 3–5 short exclusive options in one row, in a form or a filter.
- [`dropdown`](https://koobiq.io/en/components/dropdown.md) — a menu of actions or options beside a trigger, with disabled, loading and footer states.
- [`timezone`](https://koobiq.io/en/components/timezone.md) — timezone selection; `kbq-select` with a timezone option template, no multiple selection.
- [`time-range`](https://koobiq.io/en/components/time-range.md) — a period: a preset, or boundaries entered by hand.

### Data entry

- [`form-field`](https://koobiq.io/en/components/form-field.md) — the wrapper that gives a control its label, hint, error and cleaner; input, select, textarea, autocomplete, tag input, tag autocomplete, timepicker, timezone and tree select are built to sit inside it.
- [`input`](https://koobiq.io/en/components/input.md) — text, number and password entry with formatting, masks and validation.
- [`textarea`](https://koobiq.io/en/components/textarea.md) — multi-line text.
- [`datepicker`](https://koobiq.io/en/components/datepicker.md) — a date, typed or picked from the calendar; `minDate`/`maxDate` bound the calendar, `min`/`max` on the input drive validation.
- [`timepicker`](https://koobiq.io/en/components/timepicker.md) — a time, typed into a masked field.
- [`file-upload`](https://koobiq.io/en/components/file-upload.md) — files, single or multiple, with a drop area, sizes, icons and per-file errors.
- [`search-expandable`](https://koobiq.io/en/components/search-expandable.md) — a search field that expands from an icon button; it is a form control and throws without one.
- [`inline-edit`](https://koobiq.io/en/components/inline-edit.md) — edit a value where it is displayed, saving at once. → a form for creation, dependent fields, complex validation or critical data.
- [`filter-bar`](https://koobiq.io/en/components/filter-bar.md) — filtering a table or a list: typed pipes, search inside pipes, required and locked filters, saved filters, state restore.

### Actions

- [`button`](https://koobiq.io/en/components/button.md) — an action, on a native `<button>` or `<a>`; `kbq-progress` for actions over 1–2 s.
- [`icon-button`](https://koobiq.io/en/components/icon-button.md) — an action that needs no label.
- [`button-group`](https://koobiq.io/en/components/button-group.md) — buttons that belong together, styled as one control. → [`split-button`](https://koobiq.io/en/components/split-button.md) for a main action plus variants, [`button-toggle`](https://koobiq.io/en/components/button-toggle.md) to choose a value.
- [`split-button`](https://koobiq.io/en/components/split-button.md) — one dominant action plus a menu of its variants. Only when a single action covers most of the use; otherwise a [`dropdown`](https://koobiq.io/en/components/dropdown.md).
- [`actions-panel`](https://koobiq.io/en/components/actions-panel.md) — a panel of bulk actions over the current selection, with the count.
- [`link`](https://koobiq.io/en/components/link.md) — navigation between pages; the pseudo-link variant for a button inside running text.

### Feedback and status

- [`alert`](https://koobiq.io/en/components/alert.md) — a standing message in the page: a hint, a status change, a problem. Non-closable when the system reports the problem.
- [`toast`](https://koobiq.io/en/components/toast.md) — a transient message in the corner, for when no answer is required and missing it is acceptable.
- [`modal`](https://koobiq.io/en/components/modal.md) — a window that blocks the page, for a short task or an answer the system is waiting for. → [`popover`](https://koobiq.io/en/components/popover.md), [`sidepanel`](https://koobiq.io/en/components/sidepanel.md), an inline form or undo wherever modality is avoidable.
- [`notification-center`](https://koobiq.io/en/components/notification-center.md) — the list of application notifications, opened from the navbar, grouped by date with an unread counter.
- [`empty-state`](https://koobiq.io/en/components/empty-state.md) — a placeholder where content, results or a successful load are missing.
- [`progress-bar`](https://koobiq.io/en/components/progress-bar.md) — a measurable share of a long process, ideally with the remaining time beside it.
- [`progress-spinner`](https://koobiq.io/en/components/progress-spinner.md) — an unquantified or short wait, or one element loading.
- [`loader-overlay`](https://koobiq.io/en/components/loader-overlay.md) — a block that is busy, with interaction suppressed.
- [`skeleton`](https://koobiq.io/en/components/skeleton.md) — the shape of content that is loading for 2–10 s, so the layout does not jump.
- [`badge`](https://koobiq.io/en/components/badge.md) — a status, count or characteristic of an object, on its own.

### Overlays

- [`popover`](https://koobiq.io/en/components/popover.md) — a non-modal dialog by a trigger that may hold inputs and buttons; it captures focus and supports Tab inside.
- [`tooltip`](https://koobiq.io/en/components/tooltip.md) — a short hint on hover or focus, text only.
- [`kbq-title`](https://koobiq.io/en/components/title.md) — the same tooltip, but only when the element's text is actually truncated.
- [`sidepanel`](https://koobiq.io/en/components/sidepanel.md) — a window sliding from the edge over the page, modal or non-modal; non-modal panels stack with an offset. For a lot of data in a tall layout.
- [`content-panel`](https://koobiq.io/en/components/content-panel.md) — a panel that slides in and shifts the adjacent content, typically a quick preview of a table row.

### Layout and structure

- [`sidebar`](https://koobiq.io/en/components/sidebar.md) — collapsible side content that is part of the layout, with its state saved.
- [`splitter`](https://koobiq.io/en/components/splitter.md) — neighboring panels resized by dragging the separator, with constraints, snapping and collapsing.
- [`resizer`](https://koobiq.io/en/components/resizer.md) — a directive that resizes one element in a given direction by dragging.
- [`divider`](https://koobiq.io/en/components/divider.md) — a separator line, horizontal or vertical.
- [`accordion`](https://koobiq.io/en/components/accordion.md) — blocks of content the user expands on demand, in a logical order and with titles that say what is inside.
- [`tabs`](https://koobiq.io/en/components/tabs.md) — groups of content on one page, switched without a reload. → [`navbar`](https://koobiq.io/en/components/navbar.md) for main navigation, [`button-toggle`](https://koobiq.io/en/components/button-toggle.md) or [`dropdown`](https://koobiq.io/en/components/dropdown.md) to switch the view of the same data, [`radio`](https://koobiq.io/en/components/radio.md)/[`button-toggle`](https://koobiq.io/en/components/button-toggle.md) in forms.
- [`scrollbar`](https://koobiq.io/en/components/scrollbar.md) — a styled scrollbar (`hover`, `always`, `native`, `hidden`), programmatic scrolling and scroll events; `kbqScrollbarViewport` for a `cdk-virtual-scroll-viewport`, `kbqNativeScrollbar` to restyle the browser's own.
- [`overflow-items`](https://koobiq.io/en/components/overflow-items.md) — a row of items that collapses to the container width, from the end or from the start.
- [`clamped-text`](https://koobiq.io/en/components/clamped-text.md) — long text collapsed to a number of lines, with an expand trigger.
- [`clamped-list`](https://koobiq.io/en/components/clamped-list.md) — a long list collapsed to a number of items, with an expand trigger.
- [`ellipsis-center`](https://koobiq.io/en/components/ellipsis-center.md) — a single line truncated in the middle, keeping the start and the end readable.
- [`layout-flex`](https://koobiq.io/en/components/layout-flex.md) — CSS classes for arranging, aligning and ordering flex children.

### Navigation

- [`navbar`](https://koobiq.io/en/components/navbar.md) — the product's main menu, top or left, with room for the app switcher, the main action, the notification center and search.
- [`top-bar`](https://koobiq.io/en/components/top-bar.md) — a toolbar that stays visible on the screen: logo, title, breadcrumbs, actions.
- [`breadcrumbs`](https://koobiq.io/en/components/breadcrumbs.md) — the path to the current page, collapsing into a dropdown under `max`; every item needs a `routerLink`.
- [`app-switcher`](https://koobiq.io/en/components/app-switcher.md) — switching between applications and platforms.

### Data display

- [`table`](https://koobiq.io/en/components/table.md) — a plain HTML table with Koobiq styling, sticky header and border options; no sorting, no column resizing. → AG Grid for either.
- [`ag-grid`](https://koobiq.io/en/components/ag-grid.md) — tabular data in columns with sorting, filtering, column resizing or reordering, row selection or virtual scrolling.
- [`dl`](https://koobiq.io/en/components/dl.md) — term and description pairs, adaptive, horizontal or vertical, optionally with resizable columns.
- [`username`](https://koobiq.io/en/components/username.md) — the attributes that identify an internal system user.
- [`flag`](https://koobiq.io/en/components/flag.md) — a country flag, shaped and cropped from the image you project or pass as `svg`.
- [`icon`](https://koobiq.io/en/components/icon.md) — an icon from the `@koobiq/icons` font.
- [`icon-item`](https://koobiq.io/en/components/icon-item.md) — an icon on a backing, where graphics should draw attention instead of an illustration.

### Content rendering

- [`markdown`](https://koobiq.io/en/components/markdown.md) — a Markdown string rendered as HTML; needs `marked`.
- [`code-block`](https://koobiq.io/en/components/code-block.md) — source code with syntax highlighting; needs `highlight.js@^11`.
- [`dynamic-translation`](https://koobiq.io/en/components/dynamic-translation.md) — components, links and styled fragments embedded into an already-translated string.
- [`kbqHighlightBackground`](https://koobiq.io/en/components/highlight.md) / [`mcHighlight`](https://koobiq.io/en/components/highlight.md) pipes — the matched substring marked up in a result, as a background or in bold.

### Not components

- [`core`](https://koobiq.io/en/components/core.md) — the shared entry point: behaviors, a11y, keycodes, locales, overlay helpers, selection models, theming, formatters, validators and the test helpers.
- [`DateFormatter`](https://koobiq.io/en/other/date-formatter.md) — dates and times in the corporate format, following the active locale.
- [`number-formatter`](https://koobiq.io/en/other/number-formatter.md) / [`filesize-formatter`](https://koobiq.io/en/other/filesize-formatter.md) — numbers and byte sizes in the conventions of the current locale.
- [`ErrorStateMatcher`](https://koobiq.io/en/other/validation.md) — the policy that decides _when_ a control shows the errors it already has.
- [`forms`](https://koobiq.io/en/other/forms.md) — layout utilities arranging fields, labels, hints and messages in horizontal, vertical or grouped layouts.
- [`typography`](https://koobiq.io/en/main/typography.md) / [`theming`](https://koobiq.io/en/main/theming.md) — the font scale and the token-driven themes.