4.4 KiB
4.4 KiB
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 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-Design-Guidelines.md
- Issues/README.md
How to read the component docs
Each component doc is structured the same way:
- What it does — a one-line description
- Quick example — the shortest possible usage that produces a result
- All the options — every parameter explained
- Real-world examples — usage in context (inside a form, inside a page, with HTMX attributes)
- 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 |
| Avatar | Circular user icon — image or initials fallback | Avatar.md |
| Badge | Small coloured label pill | Badge.md |
| Breadcrumb | Navigation trail showing current location | Breadcrumb.md |
| Card | Bordered container with optional header and footer | Card.md |
| Progress | Horizontal fill bar showing a percentage | Progress.md |
| Separator | Horizontal or vertical divider line | Separator.md |
| Skeleton | Animated loading placeholder | Skeleton.md |
| Table | Styled data table with headers and rows | Table.md |
| Tooltip | Hover hint above any element (pure CSS) | 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 |
| Checkbox | Single on/off tick box | Checkbox.md |
| FileInput | File upload field | FileInput.md |
| Input | Single-line text field | Input.md |
| RadioGroup | Group of mutually exclusive options | RadioGroup.md |
| Select | Dropdown list | Select.md |
| Slider | Range input for numeric values | Slider.md |
| Switch | On/off toggle | Switch.md |
| Textarea | Multi-line text field | 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 |
| Calendar | Single-date picker | Calendar.md |
| CalendarRange | Date range picker | CalendarRange.md |
| Dialog | Modal overlay using native <dialog> |
Dialog.md |
| DropdownMenu | Button that opens a floating action list | DropdownMenu.md |
| Tabs | Tabbed panel switcher | Tabs.md |
| TimePicker | Hour/minute selector | TimePicker.md |
Notification components
| Component | What it is | Doc |
|---|---|---|
| ToastViewport | Fixed container that holds toast notifications — place once in MainLayout |
ToastViewport.md |
| Toast | Transient notification triggered from JavaScript via window.showToast(...) |
Toast.md |
Navigation components
| Component | What it is | Doc |
|---|---|---|
| Breadcrumb | Location trail | Breadcrumb.md |
| Pagination | Numbered page navigation row | Pagination.md |