Rewrote all the docs - more noob friendly now.
Co-authored-by: Copilot <copilot@github.com>
This commit is contained in:
+40
-59
@@ -1,45 +1,25 @@
|
||||
# Table
|
||||
|
||||
A styled HTML data table with a header row, optional caption, optional footer row, and one or more data rows. All data is plain strings.
|
||||
A styled HTML table with a header row, data rows, and optional caption and footer. Use it when you have a list of items with multiple columns — user lists, order history, product inventories.
|
||||
|
||||
---
|
||||
|
||||
## HTML structure
|
||||
## Quick example
|
||||
|
||||
```
|
||||
div.overflow-auto.rounded-md.border.border-border
|
||||
table.w-full.text-sm.caption-bottom
|
||||
caption.mt-4.text-sm.text-muted-foreground ← omitted when empty
|
||||
{caption}
|
||||
thead
|
||||
tr.border-b.bg-muted/50
|
||||
th.h-12.px-4.text-left.font-medium ← one per header
|
||||
{header}
|
||||
tbody
|
||||
tr.border-b.hover:bg-muted/40 ← one per row; last row has no border
|
||||
td.p-4 ← one per cell; raw HTML
|
||||
{cell}
|
||||
tfoot ← omitted when empty
|
||||
tr
|
||||
td[colspan=N].p-4.text-muted-foreground
|
||||
{footer}
|
||||
```csharp
|
||||
new Table(
|
||||
headers: new[] { "Name", "Email", "Role" },
|
||||
rows: users.Select(u => new[]
|
||||
{
|
||||
System.Web.HttpUtility.HtmlEncode(u.DisplayName ?? ""),
|
||||
System.Web.HttpUtility.HtmlEncode(u.Email),
|
||||
u.Role
|
||||
}))
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CSS mechanics
|
||||
|
||||
| Class | Effect |
|
||||
|---|---|
|
||||
| `overflow-auto` on wrapper | Horizontal scroll on small screens |
|
||||
| `bg-muted/50` on header | Slightly tinted header row |
|
||||
| `hover:bg-muted/40` on data rows | Subtle hover highlight |
|
||||
| `border-b` on rows | Row separator lines |
|
||||
| `caption-bottom` | Caption appears below the table |
|
||||
|
||||
---
|
||||
|
||||
## Constructor signature
|
||||
## All the options
|
||||
|
||||
```csharp
|
||||
public Table(
|
||||
@@ -49,33 +29,27 @@ public Table(
|
||||
string footer = "")
|
||||
```
|
||||
|
||||
| Parameter | Description |
|
||||
| Parameter | What it does |
|
||||
|---|---|
|
||||
| `headers` | Column heading strings |
|
||||
| `rows` | Each inner `IEnumerable<string>` is one row; cells are raw HTML |
|
||||
| `caption` | Optional caption below the table |
|
||||
| `footer` | Optional footer cell (spans all columns) |
|
||||
| `headers` | Column heading strings. |
|
||||
| `rows` | Each inner collection is one table row. Each string in it is a cell. Cells are raw HTML. |
|
||||
| `caption` | Optional summary text displayed below the table. |
|
||||
| `footer` | Optional footer text that spans all columns. |
|
||||
|
||||
> **HTML safety:** Cell values are inserted as raw HTML. Always use `System.Web.HttpUtility.HtmlEncode()` on any user-supplied strings before passing them in.
|
||||
|
||||
---
|
||||
|
||||
## Usage examples
|
||||
## Real-world examples
|
||||
|
||||
### Basic data table
|
||||
|
||||
```csharp
|
||||
new Table(
|
||||
headers: new[] { "Name", "Email", "Role" },
|
||||
rows: users.Select(u => new[] { u.DisplayName ?? "", u.Email, u.Role }))
|
||||
```
|
||||
|
||||
### With caption and footer
|
||||
### Table with a count caption and footer note
|
||||
|
||||
```csharp
|
||||
new Table(
|
||||
headers: new[] { "Product", "Price", "Stock" },
|
||||
rows: products.Select(p => new[]
|
||||
{
|
||||
p.Name,
|
||||
System.Web.HttpUtility.HtmlEncode(p.Name),
|
||||
$"${p.Price:F2}",
|
||||
p.Stock.ToString()
|
||||
}),
|
||||
@@ -83,14 +57,15 @@ new Table(
|
||||
footer: "Prices include VAT")
|
||||
```
|
||||
|
||||
### Cells with HTML content (e.g. badges)
|
||||
### Status column with a Badge
|
||||
|
||||
Pre-render the badge to an HTML string and embed it in the cell:
|
||||
|
||||
```csharp
|
||||
// Pre-render a Badge to HTML string
|
||||
string ActiveBadge()
|
||||
string RenderBadge(string label, string variant = "default")
|
||||
{
|
||||
var buf = new System.Buffers.ArrayBufferWriter<byte>();
|
||||
new Badge("Active").Render(new HtmxRenderContext(buf));
|
||||
new Badge(label, variant).Render(new HtmxRenderContext(buf));
|
||||
return System.Text.Encoding.UTF8.GetString(buf.WrittenSpan);
|
||||
}
|
||||
|
||||
@@ -99,28 +74,34 @@ new Table(
|
||||
rows: users.Select(u => new[]
|
||||
{
|
||||
System.Web.HttpUtility.HtmlEncode(u.DisplayName ?? ""),
|
||||
u.IsActive ? ActiveBadge() : ""
|
||||
u.IsActive ? RenderBadge("Active", "default") : RenderBadge("Inactive", "secondary")
|
||||
}))
|
||||
```
|
||||
|
||||
### With action buttons per row
|
||||
### Row actions with HTMX edit button
|
||||
|
||||
```csharp
|
||||
string EditBtn(string id) => $"""
|
||||
<button hx-get="/users/{id}/edit" hx-target="#modal" class="text-sm underline">Edit</button>
|
||||
""";
|
||||
string EditLink(string id) =>
|
||||
$"""<button hx-get="/users/{id}/edit" hx-target="#modal" class="text-sm underline">Edit</button>""";
|
||||
|
||||
new Table(
|
||||
headers: new[] { "Name", "Actions" },
|
||||
headers: new[] { "Name", "" },
|
||||
rows: users.Select(u => new[]
|
||||
{
|
||||
System.Web.HttpUtility.HtmlEncode(u.DisplayName ?? ""),
|
||||
EditBtn(u.Id!)
|
||||
EditLink(u.Id!)
|
||||
}))
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## How it works
|
||||
|
||||
Table wraps a standard `<table>` in an `overflow-auto` container so it scrolls horizontally on small screens. Header cells use `<th>` and data cells use `<td>`. The `caption` is rendered inside a `<caption>` element below the table; the `footer` spans all columns in a `<tfoot>` row.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tips and tricks
|
||||
|
||||
- Cells are raw HTML — HTML-encode any user-supplied string values before inserting them to prevent XSS.
|
||||
|
||||
Reference in New Issue
Block a user