shaamilahmed/Htmx
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Rewrote all the docs - more noob friendly now.

Browse Source 
Co-authored-by: Copilot <copilot@github.com>
This commit is contained in:
Enciphered
2026-05-05 23:55:26 +05:00
parent c1e1f74557
commit b530bb8c97
35 changed files with 2159 additions and 2341 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/Components/Badge.md
+56 -62
View File
@@ -1,108 +1,102 @@
# Badge
A small inline label pill. Used to indicate status, category, or count. Four variants cover most use-cases.
A small coloured pill label — the kind you see next to a status field that says "Active", "Pending", or "Error".
---
## HTML structure
## Quick example
```
span.{base classes + variant classes}
{text}
```csharp
new Badge("Active")
new Badge("Pending", variant: "secondary")
new Badge("Error", variant: "destructive")
new Badge("Draft", variant: "outline")
```
---
## CSS mechanics
| Class | Effect |
|---|---|
| `inline-flex items-center rounded-full` | Pill shape that sits inline with text |
| `px-2.5 py-0.5 text-xs font-semibold` | Compact size and bold label |
| `transition-colors` | Smooth color changes on hover |
| `focus:ring-2 focus:ring-ring focus:ring-offset-2` | Keyboard focus outline |
**Variants:**
| Variant | Classes |
|---|---|
| `default` | `bg-primary text-primary-foreground hover:bg-primary/80` |
| `secondary` | `bg-secondary text-secondary-foreground hover:bg-secondary/80` |
| `destructive` | `bg-destructive text-destructive-foreground hover:bg-destructive/80` |
| `outline` | `text-foreground border border-input hover:bg-accent` |
---
## Constructor signature
## All the options
```csharp
public Badge(string text, string variant = "default")
```
| Parameter | Description |
| Parameter | What it does |
|---|---|
| `text` | Label displayed inside the badge |
| `variant` | `"default"` / `"secondary"` / `"destructive"` / `"outline"` |
| `text` | The label inside the pill |
| `variant` | The colour scheme: `"default"` (primary colour), `"secondary"` (muted), `"destructive"` (red), `"outline"` (border only) |
---
## Usage examples
## Real-world examples
### Basic badges
### Status column in a user table
When you need a Badge inside a table cell (which takes a raw HTML string), render it to a string first:
```csharp
new Badge("New")
new Badge("Beta", variant: "secondary")
new Badge("Error", variant: "destructive")
new Badge("Pending", variant: "outline")
```
### Status indicator in a table cell
```csharp
// Render to bytes and embed in table cell HTML
var writer = new System.Buffers.ArrayBufferWriter<byte>();
new Badge("Active", variant: "default").Render(new HtmxRenderContext(writer));
var badgeHtml = System.Text.Encoding.UTF8.GetString(writer.WrittenSpan);
static string RenderBadge(string text, string variant)
{
var writer = new System.Buffers.ArrayBufferWriter<byte>();
new Badge(text, variant).Render(new HtmxRenderContext(writer));
return System.Text.Encoding.UTF8.GetString(writer.WrittenSpan);
}
new Table(
headers: new[] { "Name", "Status" },
rows: users.Select(u => new[] { u.DisplayName ?? "", badgeHtml }))
headers: new[] { "Name", "Role", "Status" },
rows: users.Select(u => new[]
{
u.DisplayName ?? "",
u.Role,
RenderBadge(u.IsActive ? "Active" : "Suspended",
u.IsActive ? "default" : "destructive"),
}))
```
### Embedding in a page slot
### Dynamic variant based on data
```csharp
var badge = order.Status switch
{
"complete" => new Badge("Complete"),
"pending" => new Badge("Pending", variant: "secondary"),
"cancelled" => new Badge("Cancelled", variant: "destructive"),
_ => new Badge(order.Status, variant: "outline"),
};
```
### Inside a page slot
```html
<!-- MyPage.htmx -->
<div class="flex items-center gap-2">
<span class="text-sm">Status:</span>
<span>Status:</span>
$$StatusBadge$$
</div>
```
```csharp
// MyPage.htmx.cs
public IHtmxComponent StatusBadge { get; }
public MyPage(string status)
public sealed class MyPage : MyPageBase
{
StatusBadge = status == "active"
? new Badge("Active")
: new Badge("Inactive", variant: "secondary");
}
private readonly IHtmxComponent _statusBadge;
protected override void RenderStatusBadge(HtmxRenderContext ctx)
=> StatusBadge.Render(ctx.Next());
public MyPage(string status)
{
_statusBadge = new Badge(status == "active" ? "Active" : "Inactive",
status == "active" ? "default" : "secondary");
}
protected override void RenderStatusBadge(HtmxRenderContext ctx)
=> _statusBadge.Render(ctx.Next());
}
```
---
## Tips and tricks
## How it works
- Badge does not have a click handler — wrap it in an `<a>` or a `Button` if you need interactivity.
- All four variants respond to focus, so a Badge embedded inside a focusable element will show a ring.
- For a count badge (e.g. `"3 new"`) just include the count in the text string.
- To render a Badge inside raw HTML strings (e.g. inside a `Table` cell or `Card` content), render it eagerly to a string in the constructor rather than relying on slot rendering.
Badge is a `<span>` with `rounded-full` giving it the pill shape. The four variants are just different combinations of background and text colour classes. Badge is a purely server-rendered display element — it has no JavaScript and no click behaviour. If you need a clickable badge, wrap it in an `<a>` tag or use a `Button` component with a `link` variant.
---