Rewrote all the docs - more noob friendly now.
Co-authored-by: Copilot <copilot@github.com>
This commit is contained in:
+41
-59
@@ -1,35 +1,20 @@
|
||||
# Alert
|
||||
|
||||
A contextual callout box for informational or error messages. Two variants: `default` (neutral) and `destructive` (red). An optional inline SVG icon is positioned automatically.
|
||||
A coloured callout box that draws the user's attention — like a sticky note placed on top of the page. Use it to show errors, warnings, or helpful information.
|
||||
|
||||
---
|
||||
|
||||
## HTML structure
|
||||
## Quick example
|
||||
|
||||
```
|
||||
div[role=alert].{variant classes}
|
||||
{icon SVG} ← positioned absolute top-left via Tailwind arbitrary selectors
|
||||
div
|
||||
h5.font-medium ← title (always rendered)
|
||||
div.text-sm ← description (omitted when empty)
|
||||
```csharp
|
||||
new Alert(
|
||||
title: "Heads up",
|
||||
description: "Your session expires in 5 minutes.")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CSS mechanics
|
||||
|
||||
| Class / selector | Effect |
|
||||
|---|---|
|
||||
| `[&>svg]:absolute [&>svg]:left-4 [&>svg]:top-4` | Positions any direct SVG child at top-left |
|
||||
| `[&>svg~*]:pl-7` | Adds left padding to all siblings after the SVG so text is not covered by the icon |
|
||||
| `[&>svg+div]:translate-y-[-3px]` | Vertically aligns the text div with the icon center |
|
||||
| `border-destructive/50 text-destructive` | Red destructive variant |
|
||||
|
||||
The arbitrary selector approach (`[&>svg]:*`) means you can pass any SVG and it will be positioned correctly without extra wrapper divs.
|
||||
|
||||
---
|
||||
|
||||
## Constructor signature
|
||||
## All the options
|
||||
|
||||
```csharp
|
||||
public Alert(
|
||||
@@ -39,66 +24,63 @@ public Alert(
|
||||
string icon = "")
|
||||
```
|
||||
|
||||
| Parameter | Description |
|
||||
| Parameter | What it does |
|
||||
|---|---|
|
||||
| `title` | Required heading text |
|
||||
| `description` | Optional body text below the title |
|
||||
| `variant` | `"default"` or `"destructive"` |
|
||||
| `icon` | Raw SVG string; omit for a text-only alert |
|
||||
| `title` | The bold heading line — always shown |
|
||||
| `description` | A second line of detail below the title — optional |
|
||||
| `variant` | `"default"` (neutral, grey border) or `"destructive"` (red) |
|
||||
| `icon` | A raw SVG string placed to the left of the text — omit for no icon |
|
||||
|
||||
---
|
||||
|
||||
## Usage examples
|
||||
## Real-world examples
|
||||
|
||||
### Informational (no icon)
|
||||
### Login error
|
||||
|
||||
```csharp
|
||||
new Alert(
|
||||
title: "Heads up",
|
||||
description: "Your session expires in 5 minutes.")
|
||||
```
|
||||
|
||||
### Destructive
|
||||
|
||||
```csharp
|
||||
new Alert(
|
||||
title: "Error",
|
||||
description: "Invalid email or password.",
|
||||
title: "Sign in failed",
|
||||
description: "The email or password you entered is incorrect.",
|
||||
variant: "destructive")
|
||||
```
|
||||
|
||||
### With an icon
|
||||
### Success confirmation
|
||||
|
||||
```csharp
|
||||
new Alert(title: "Changes saved successfully.")
|
||||
```
|
||||
|
||||
### Info notice with a link in the description
|
||||
|
||||
`description` is raw HTML, so you can embed links:
|
||||
|
||||
```csharp
|
||||
new Alert(
|
||||
title: "New message",
|
||||
description: "You have 3 unread messages.",
|
||||
variant: "default",
|
||||
icon: """
|
||||
<svg xmlns="http://www.w3.org/2000/svg" class="h-4 w-4" viewBox="0 0 24 24"
|
||||
fill="none" stroke="currentColor" stroke-width="2"
|
||||
stroke-linecap="round" stroke-linejoin="round">
|
||||
<path d="M22 16.92v3a2 2 0 01-2.18 2 19.79 19.79 0 01-8.63-3.07
|
||||
A19.5 19.5 0 013.07 9.77a19.79 19.79 0 01-3.07-8.67
|
||||
A2 2 0 012 .18L5 0a2 2 0 012 1.72 ..."/>
|
||||
</svg>
|
||||
""")
|
||||
title: "Maintenance scheduled",
|
||||
description: "The system will be offline on Saturday. <a href='/status' class='underline'>View status page</a>.")
|
||||
```
|
||||
|
||||
### Title-only
|
||||
### Conditional error slot on a form page
|
||||
|
||||
A common pattern is to render the alert only when there is something to show. In the page constructor:
|
||||
|
||||
```csharp
|
||||
new Alert(title: "Changes saved successfully.", variant: "default")
|
||||
// Store empty bytes when there's no error — WriteUtf8 on empty bytes is a no-op
|
||||
_errorAlertData = string.IsNullOrEmpty(errorMessage)
|
||||
? []
|
||||
: new Alert(title: "Error", description: errorMessage, variant: "destructive")
|
||||
.ToRenderedBytes();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tips and tricks
|
||||
## How it works
|
||||
|
||||
- The icon SVG should be `h-4 w-4` — larger sizes will push text out of alignment.
|
||||
- For the `destructive` variant the icon automatically inherits `text-destructive` color via the variant class.
|
||||
- The `description` slot is a raw HTML string — you can include `<a>` links or `<code>` spans.
|
||||
- Use `Alert` inside a page's optional error slot rather than always rendering it — pass an empty byte array (`[]`) when there is no error so the slot renders nothing.
|
||||
The alert is a `<div role="alert">` — this tells screen readers to announce its content immediately when it appears on the page.
|
||||
|
||||
If you pass an `icon`, it is placed as a direct child SVG. Tailwind's arbitrary selector `[&>svg]:absolute` positions it at the top-left corner automatically, and `[&>svg~*]:pl-7` shifts all the text to the right so nothing overlaps. You do not need any wrapper divs around your SVG.
|
||||
|
||||
The icon should be `class="h-4 w-4"` — larger icons will misalign the text.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user