Rewrote all the docs - more noob friendly now.
Co-authored-by: Copilot <copilot@github.com>
This commit is contained in:
+54
-68
@@ -1,36 +1,21 @@
|
||||
# Card
|
||||
|
||||
A styled container with optional header (title + description) and footer sections. The body content is always rendered; header and footer are conditionally included.
|
||||
A bordered box for grouping related content — like a physical card you might hold in your hand. It has three distinct zones: a header (title + subtitle), a body (your content), and a footer (usually actions).
|
||||
|
||||
---
|
||||
|
||||
## HTML structure
|
||||
## Quick example
|
||||
|
||||
```
|
||||
div.rounded-lg.border.border-border.bg-card.text-card-foreground.shadow-sm.{extraClasses}
|
||||
div.flex.flex-col.space-y-1.5.p-6 ← header (omitted when no title/description)
|
||||
h3.text-2xl.font-semibold ← title
|
||||
p.text-sm.text-muted-foreground ← description
|
||||
div.p-6.pt-0 ← content (always present)
|
||||
{content}
|
||||
div.flex.items-center.p-6.pt-0 ← footer (omitted when empty)
|
||||
{footer}
|
||||
```csharp
|
||||
new Card(
|
||||
content: "<p>Your subscription renews on July 1.</p>",
|
||||
title: "Billing",
|
||||
description: "Current plan: Pro")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CSS mechanics
|
||||
|
||||
| Class | Effect |
|
||||
|---|---|
|
||||
| `bg-card text-card-foreground` | Pulls from CSS variables — dark mode works automatically |
|
||||
| `rounded-lg border border-border shadow-sm` | Subtle rounded box with border and drop shadow |
|
||||
| `p-6 pt-0` on content | Full padding except top (header provides the top spacing) |
|
||||
| `space-y-1.5` on header | Controlled gap between title and description |
|
||||
|
||||
---
|
||||
|
||||
## Constructor signature
|
||||
## All the options
|
||||
|
||||
```csharp
|
||||
public Card(
|
||||
@@ -41,77 +26,78 @@ public Card(
|
||||
string extraClasses = "")
|
||||
```
|
||||
|
||||
| Parameter | Description |
|
||||
| Parameter | What it does |
|
||||
|---|---|
|
||||
| `content` | Raw HTML for the card body (always rendered) |
|
||||
| `title` | Optional heading in the header area |
|
||||
| `description` | Optional subheading below the title |
|
||||
| `footer` | Optional raw HTML in the footer area |
|
||||
| `extraClasses` | Additional Tailwind classes on the outer `div` |
|
||||
| `content` | The body of the card — always shown. Raw HTML. |
|
||||
| `title` | Optional bold heading at the top of the card. |
|
||||
| `description` | Optional smaller subtitle below the title. |
|
||||
| `footer` | Optional section at the bottom, typically holding action buttons. Raw HTML. |
|
||||
| `extraClasses` | Additional Tailwind classes on the outer `div` — useful for `max-w-sm`, `col-span-2`, etc. |
|
||||
|
||||
The header section (title + description) is omitted entirely when both are empty. Same for the footer.
|
||||
|
||||
---
|
||||
|
||||
## Usage examples
|
||||
## Real-world examples
|
||||
|
||||
### Simple content card
|
||||
|
||||
```csharp
|
||||
new Card(content: "<p>Your subscription renews on July 1.</p>")
|
||||
```
|
||||
|
||||
### Card with title and description
|
||||
### A stats card on a dashboard
|
||||
|
||||
```csharp
|
||||
new Card(
|
||||
content: "<p>Manage your billing details and invoices.</p>",
|
||||
title: "Billing",
|
||||
description: "Your current plan: Pro")
|
||||
title: "Total Users",
|
||||
description: "All registered accounts",
|
||||
content: $"<p class=\"text-4xl font-bold\">{userCount:N0}</p>")
|
||||
```
|
||||
|
||||
### Card with footer actions
|
||||
### A confirmation card with footer buttons
|
||||
|
||||
Buttons and other components need to be pre-rendered to HTML strings when used inside `content` or `footer`:
|
||||
|
||||
```csharp
|
||||
string ToHtml(IHtmxComponent c)
|
||||
{
|
||||
var w = new System.Buffers.ArrayBufferWriter<byte>();
|
||||
c.Render(new HtmxRenderContext(w));
|
||||
return System.Text.Encoding.UTF8.GetString(w.WrittenSpan);
|
||||
}
|
||||
|
||||
new Card(
|
||||
content: "<p>Are you sure you want to cancel your account?</p>",
|
||||
title: "Delete account",
|
||||
description: "This action cannot be undone.",
|
||||
footer: """
|
||||
<button class="inline-flex h-9 rounded-md border border-input px-4 text-sm mr-2">Cancel</button>
|
||||
<button class="inline-flex h-9 rounded-md bg-destructive text-destructive-foreground px-4 text-sm">Delete</button>
|
||||
""")
|
||||
content: "<p>All your data will be permanently removed.</p>",
|
||||
footer: ToHtml(new Button("Cancel", variant: "outline"))
|
||||
+ ToHtml(new Button("Delete", variant: "destructive", type: "submit")))
|
||||
```
|
||||
|
||||
### Constrained width
|
||||
### A grid of cards
|
||||
|
||||
Cards are most commonly placed in a CSS grid in the page template:
|
||||
|
||||
```html
|
||||
<div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-6">
|
||||
$$Card1$$
|
||||
$$Card2$$
|
||||
$$Card3$$
|
||||
</div>
|
||||
```
|
||||
|
||||
### Constrained width (e.g. a login card)
|
||||
|
||||
```csharp
|
||||
new Card(
|
||||
content: "<p>Hello world</p>",
|
||||
title: "Welcome",
|
||||
content: "...login form HTML...",
|
||||
title: "Welcome back",
|
||||
description: "Sign in to your account",
|
||||
extraClasses: "max-w-sm mx-auto")
|
||||
```
|
||||
|
||||
### Embedding a component as content
|
||||
|
||||
```csharp
|
||||
// Render a Badge to a string then embed in the card body
|
||||
var writer = new System.Buffers.ArrayBufferWriter<byte>();
|
||||
new Badge("Active").Render(new HtmxRenderContext(writer));
|
||||
var badgeHtml = System.Text.Encoding.UTF8.GetString(writer.WrittenSpan);
|
||||
|
||||
new Card(
|
||||
content: $"<p class='mb-2'>Status:</p>{badgeHtml}",
|
||||
title: "Account")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tips and tricks
|
||||
## How it works
|
||||
|
||||
- `content`, `footer`, title, and description are inserted as raw HTML — HTML-encode any user-supplied strings before passing them in.
|
||||
- Use `extraClasses` to set max-width, margin, or custom background without subclassing.
|
||||
- If you need a completely custom header layout, omit `title` and `description` and build the header HTML in `content`, adding `p-6` padding yourself.
|
||||
- Cards can be placed in a CSS grid: `<div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">`.
|
||||
- Cards can be placed in a CSS grid: `<div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">`.
|
||||
Card uses CSS variables (`bg-card`, `text-card-foreground`, `border-border`) which automatically adapt to dark mode. The header and footer sections are skipped entirely in the rendered HTML when they are not needed — they do not leave empty divs behind.
|
||||
|
||||
All strings passed to `content` and `footer` are raw HTML. HTML-encode any user-supplied values before passing them in.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user