# Component Reference

All components live in `Htmx.ApiDemo/Templates/Components/`. Each is a `.htmx` template and a `.htmx.cs` class pair. You create one with `new ComponentName(...)` and drop it into any page slot.

If you have not read [03-creating-a-component.md](03-creating-a-component.md) yet, start there — it explains how components work under the hood.

For known API limitations and improvement tracking, also see:

- [Issues/Components/00-API-Limitations-and-Workarounds.md](Issues/Components/00-API-Limitations-and-Workarounds.md)
- [Issues/Components/00-API-Design-Guidelines.md](Issues/Components/00-API-Design-Guidelines.md)
- [Issues/README.md](Issues/README.md)

---

## How to read the component docs

Each component doc is structured the same way:

1. **What it does** — a one-line description
2. **Quick example** — the shortest possible usage that produces a result
3. **All the options** — every parameter explained
4. **Real-world examples** — usage in context (inside a form, inside a page, with HTMX attributes)
5. **How it works** — CSS mechanics and any JavaScript, for when you need to customise it

---

## Display components

These render static visual elements. No JavaScript required.

| Component | What it is | Doc |
|---|---|---|
| Alert | Coloured callout box for messages and errors | [Alert.md](Components/Alert.md) |
| Avatar | Circular user icon — image or initials fallback | [Avatar.md](Components/Avatar.md) |
| Badge | Small coloured label pill | [Badge.md](Components/Badge.md) |
| Breadcrumb | Navigation trail showing current location | [Breadcrumb.md](Components/Breadcrumb.md) |
| Card | Bordered container with optional header and footer | [Card.md](Components/Card.md) |
| Progress | Horizontal fill bar showing a percentage | [Progress.md](Components/Progress.md) |
| Separator | Horizontal or vertical divider line | [Separator.md](Components/Separator.md) |
| Skeleton | Animated loading placeholder | [Skeleton.md](Components/Skeleton.md) |
| Table | Styled data table with headers and rows | [Table.md](Components/Table.md) |
| Tooltip | Hover hint above any element (pure CSS) | [Tooltip.md](Components/Tooltip.md) |

---

## Form components

These are used inside `<form>` elements and submit their values with the form.

| Component | What it is | Doc |
|---|---|---|
| Button | Styled button — six visual variants | [Button.md](Components/Button.md) |
| Checkbox | Single on/off tick box | [Checkbox.md](Components/Checkbox.md) |
| FileInput | File upload field | [FileInput.md](Components/FileInput.md) |
| Input | Single-line text field | [Input.md](Components/Input.md) |
| RadioGroup | Group of mutually exclusive options | [RadioGroup.md](Components/RadioGroup.md) |
| Select | Dropdown list | [Select.md](Components/Select.md) |
| Slider | Range input for numeric values | [Slider.md](Components/Slider.md) |
| Switch | On/off toggle | [Switch.md](Components/Switch.md) |
| Textarea | Multi-line text field | [Textarea.md](Components/Textarea.md) |

---

## Interactive components (require JavaScript)

These components initialise client-side behaviour on `DOMContentLoaded` and `htmx:afterSwap`. The JS lives in `wwwroot/js/components.js`.

| Component | What it is | Doc |
|---|---|---|
| Accordion | Expand/collapse panel list | [Accordion.md](Components/Accordion.md) |
| Calendar | Single-date picker | [Calendar.md](Components/Calendar.md) |
| CalendarRange | Date range picker | [CalendarRange.md](Components/CalendarRange.md) |
| Dialog | Modal overlay using native `<dialog>` | [Dialog.md](Components/Dialog.md) |
| DropdownMenu | Button that opens a floating action list | [DropdownMenu.md](Components/DropdownMenu.md) |
| Tabs | Tabbed panel switcher | [Tabs.md](Components/Tabs.md) |
| TimePicker | Hour/minute selector | [TimePicker.md](Components/TimePicker.md) |

---

## Notification components

| Component | What it is | Doc |
|---|---|---|
| ToastViewport | Fixed container that holds toast notifications — place once in `MainLayout` | [ToastViewport.md](Components/ToastViewport.md) |
| Toast | Transient notification triggered from JavaScript via `window.showToast(...)` | [Toast.md](Components/Toast.md) |

---

## Navigation components

| Component | What it is | Doc |
|---|---|---|
| Breadcrumb | Location trail | [Breadcrumb.md](Components/Breadcrumb.md) |
| Pagination | Numbered page navigation row | [Pagination.md](Components/Pagination.md) |