# AstrolUI

> If you're looking to streamline development with .Net and Blazor using this technology in the lightest way possible, our free components will provide the perfect solution to boost your project.

Source page: https://doc.astrolui.com/

## ((MarkupString)$"{_localizer["hm_hero_title"]}")

Blazor components for .NET 10: examples you can try right here, code ready to copy and every parameter of each component.

Looking for something specific? Press Ctrl K to search the whole documentation.

### Start here

### Catalog

### What's new

### Community and contact

Questions, ideas or a project with AstrolUI? Write to us or follow us.

Creator of AstrolUI · LinkedIn

Basic, Charts, PDFViewer, RichText and Repository are free; Board has a commercial license. [See the license](/license)


---

# Installation

> Install the Astrol.Component.Basic package from the AstrolUI NuGet. Add in the NuGet Package Manager Settings of your Visual Studio.

Source page: https://doc.astrolui.com/basic-component/installation

## Video tutorial

## 1. Installation process

Remove all references to the css files included by default in the Blazor project template.

**AstrolUI does not include bootstrap**: **astrol-basic.min.css** ships its own reboot, icons and animations in a single file. If your app uses bootstrap classes, reference it yourself **beforeastrol-basic.min.css**.

Install the package **Astrol.Component.Basic** from [**AstrolUI's NuGet**](https://nuget.astrolui.com/) or **reference the project** in your solution.

Add the **NuGet AstrolUi** repository to the **NuGet Package Manager Settings** in your **Visual Studio**.

**Source: ** https://nuget.astrolui.com/v3/index.json [(Refer to documentation on how to configure package sources in Visual Studio)](https://learn.microsoft.com/es-es/nuget/consume-packages/install-use-packages-visual-studio#package-sources)

Insert the **.css** elements into your **index.html (WebAssembly)** or **_Host.cshtml (Blazor Server)**:

```html
<!-- Reference to the UI themes. -->
<link href="_content/Astrol.Component.Basic/css/astrol-basic.min.css" rel="stylesheet" />
```

**Register** the AstrolUI services in your app's **Program** with **AddAstrolBasic()**: it registers **AstrolJSInterop**, **IAstrolToast** (notifications) and **IAstrolModal** (confirmations and modals from code). No global **.js** file is needed anymore: each component loads its JavaScript only when it is used.

```csharp
using Astrol.Component.Basic;
public static async Task Main(string[] args) {
   //...
   //...
   ConfigureServices(builder.Services);//Add the method
   //...
   //...
}
private static void ConfigureServices(IServiceCollection services) { //New method
   services.AddAstrolBasic(); // AstrolJSInterop + IAstrolToast + IAstrolModal
}
```

## 2. Package sizes

Measured on version **10.0.13.1** in Release. **NuGet** is what is downloaded on install; the **DLL** is what the browser receives for each library (in parentheses, gzip-compressed; Blazor serves it with Brotli, even smaller). Third-party libraries (ApexCharts, pdf.js, Quill) and JavaScript modules are downloaded **only when the component that uses them appears**: a page without charts downloads nothing from ApexCharts.

An app with Basic downloads on first start about **436 KB of AstrolUI DLLs** (Basic + Entities + JSInterop, ≈ 164 KB gzipped) and **≈ 61 KB of styles and icons** compressed; after that the browser caches them. For comparison: the Basic package weighed 1,921 KB before the redesign and its global CSS 220 KB split into four files with Bootstrap.


---

# For AI

> AstrolUI documentation for AI: llms.txt, llms-full.txt and every page in Markdown with its real code, so Claude, Copilot or Cursor write correct AstrolUI code.

Source page: https://doc.astrolui.com/for-ai

The documentation in Markdown for AI assistants (llms.txt).

AI assistants (Claude Code, GitHub Copilot, Cursor, ChatGPT...) don't need to read the pages like a person: the menu, demos and styles only use up their context. That's why the documentation is also published in **Markdown**, following the [llms.txt](https://llmstxt.org) format: clean text, every component's parameters and the real example code (the same these docs run), in English.

## 1. Use it in your project

Add these lines to your assistant's instructions file (Claude Code reads **CLAUDE.md**, GitHub Copilot **.github/copilot-instructions.md** and Cursor **.cursor/rules**). Then, when it writes AstrolUI code, it checks the documentation instead of making up parameters. In a chat you can also paste the **llms-full.txt** link or the component page link.

```html
<!-- Claude Code: CLAUDE.md  ·  GitHub Copilot: .github/copilot-instructions.md  ·  Cursor: .cursor/rules/astrolui.mdc -->
## AstrolUI
This project uses AstrolUI (Blazor, .NET 10). Before writing UI code, read https://doc.astrolui.com/llms.txt
and open the page of each component you use (https://doc.astrolui.com/ai/<page>.txt).
For code written for older AstrolUI versions follow https://doc.astrolui.com/ai/migration.txt
```

## 2. From every page

At the bottom of every page there is a **Markdown for AI** link that opens the same page in AI format.

## 3. How it is kept up to date

The files are generated from the pages' texts and code, so nothing is written twice. After changing the docs, regenerate them:

```bash
python 2-Shared/tools/docs_ai_export.py      # llms.txt, llms-full.txt and wwwroot/ai/*.txt
python 2-Shared/tools/docs_search_index.py   # search index of these docs
```


---

# License

> AstrolUI license: Basic, PDFViewer, Charts, RichText and Repository are free for personal and commercial projects; Board requires a commercial license.

Source page: https://doc.astrolui.com/license

Free components and advanced packages under a commercial license.

Personal and commercial projects

A license is required to use them

#### **1.** Free packages

- They can be used at no cost in personal or commercial projects, including ones that are sold or offered as a service.
- They may not be redistributed as part of a public library, framework, template or development tool, nor sold separately.

#### **2.** Packages under a commercial license

- Using them in any project (personal or commercial) that is published or put into production requires a valid AstrolUI license.
- They can be tried without a license only in local development and test environments that don't serve end users.
- License terms (projects, developers, duration, updates and price) are agreed in writing; request one at [astrol@astrolui.com](mailto:astrol@astrolui.com).
- The NuGet repository will soon require credentials to download these packages.

#### **3.** Common terms

- **Source code:** not available. Decompiling, reverse engineering or modifying the packages is not allowed.
- **Intellectual property:** all rights to the code, design and functionality of the `Astrol.` packages belong to Asley F. Cruz. Use grants no rights beyond those stated here.
- **Support:** not guaranteed for the free packages; for commercial ones it is what each license states.
- **Liability:** the packages are provided "as is", without warranties of any kind. The author is not liable for direct or indirect damages arising from their use.
- **Third-party components:** Astrol.Component.Charts includes ApexCharts 3.50 (MIT license) and Astrol.Component.PDFViewer includes PDF.js (Apache 2.0 license); those parts are governed by their own licenses.

Official, current text: [astrolui.com/license](https://astrolui.com/license).


---

# Overview

> The basic components together, as in a real screen: buttons, tags, form, file upload, grid, confirmation and notifications.

Source page: https://doc.astrolui.com/overview

The basic components together, as in a real screen: buttons, tags, form, file upload, grid, confirmation and notifications.

### Buttons and tags

One main action per view; the rest, secondary or outlined. Press «Delete» to see the confirmation and the notifications.

Changes are synced every 5 minutes.

New: tabs, checkboxes and radios.

### Form

### File upload

### Grid


---

# Theme

> AstrolUi offers a vibrant color palette for .Net Blazor, where each color represents a unique theme. It allows for 100% customization, enabling you to personalize the themes according to your preferences.

Source page: https://doc.astrolui.com/theme

Theme color and light/dark mode. Changes apply right away, without reloading the page.

## 1. Theme color

Pick a color: the docs change right away (same as the circles in the top bar) and it is remembered next time.

## 2. Mode

Automatic follows the operating system preference and changes live when the user changes it.

## 3. Design tokens

AstrolUI exposes its visual system as CSS variables with the **--aui-** prefix. They change by themselves with the theme color (**data-aui-color**) and the mode (**data-aui-mode**), so your own CSS stays consistent without extra work.

- **Surfaces:** --aui-bg (page background), --aui-surface (cards, fields), --aui-surface-2 (headers, footers), --aui-surface-hover.
- **Text:** --aui-text, --aui-text-2 (secondary), --aui-text-3 (hints, quiet icons); --aui-link.
- **Borders:** --aui-border, --aui-border-strong.
- **Brand:** --aui-brand, --aui-brand-strong, --aui-on-brand (text on the brand), --aui-brand-soft (tint), --aui-brand-text (text on the tint), --aui-brand-ring and --aui-focus-ring (focus).
- **States:** --aui-danger, --aui-success, --aui-warning, --aui-info.
- **Shape and motion:** --aui-radius-sm / --aui-radius / --aui-radius-lg / --aui-radius-pill (6 / 8 / 12 / 999 px), --aui-h-control (38 px), --aui-shadow-sm / --aui-shadow / --aui-shadow-lg, --aui-dur, --aui-ease.
- **Typography:** --aui-font, --aui-font-mono, --aui-text-xs / sm / md / lg / xl (12 / 13 / 14 / 16 / 20 px).

The old variables (--color-base, --background, --layout-*...) still exist as aliases of these tokens so existing CSS keeps working.

```css
/* Use the tokens in your own CSS: they follow the theme color and light/dark mode */
.my-card {
    background: var(--aui-surface);
    border: 1px solid var(--aui-border);
    border-radius: var(--aui-radius-lg);
    box-shadow: var(--aui-shadow-sm);
    color: var(--aui-text);
}
.my-card small { color: var(--aui-text-2); }
.my-card .highlight { background: var(--aui-brand-soft); color: var(--aui-brand-text); }
.my-card .action { background: var(--aui-brand); color: var(--aui-on-brand); }

/* Your own brand color: override it in a theme */
[data-aui-color="blue"] { --aui-brand: #0057b8; --aui-brand-strong: #003f86; --aui-on-brand: #fff; }
```

## 4. Change the theme in your app

**AstrolLayoutMenu** applies the color (**Style**) and the mode (**Mode**). Change those variables and the layout repaints without reloading; with **AstrolThemeSwitcher** the user does it from the top bar. Save the preference wherever you want (localStorage, user profile...).

```razor
<AstrolLayoutMenu Style="@theme" Mode="@mode" OnChangeThemeMode="m => mode = m">
    <Top>
        <AstrolThemeSwitcher @bind-Theme="theme" @bind-Mode="mode" />
    </Top>
    ...
</AstrolLayoutMenu>

@code {
    private AstrolTheme theme = AstrolTheme.Yellow;
    private AstrolThemeMode mode = AstrolThemeMode.Auto;
}
```

## 5. Your own theme

Besides the six colors, AstrolUI accepts any brand color. Every component of every package (buttons, forms, table, menu, charts, board, editor, PDF viewer...) is painted with three variables: **--aui-brand**, **--aui-brand-strong** and **--aui-on-brand**; soft shades, the focus ring and the rest derive from them. With **data-aui-color="custom"** those variables come from **--aui-custom-brand** (and optionally **--aui-custom-brand-strong** and **--aui-custom-on-brand**).

**AstrolCustomTheme** (Astrol.Entities.Basic) computes all three from a single color: the strong shade and the text color (white or dark) with the most contrast. AstrolThemeSwitcher is not required: the color can come from settings, the database (one color per customer) or a color field. Pick a color here to apply it to the whole documentation.

```razor
@* 1. With AstrolLayoutMenu: Style = Custom + CustomColor (also applied to <html>) *@
<AstrolLayoutMenu Style="AstrolTheme.Custom" CustomColor="#0ea5e9" Mode="@mode"> ... </AstrolLayoutMenu>

@* 2. On any container (or <html>), without the layout *@
<div data-aui-color="custom" style="@AstrolCustomTheme.GetStyle(brandColor)">
    <AstrolButton Text="Save" />  @* buttons, grid, toggles, charts... use the color *@
</div>

@* 3. For the whole app from C# (e.g. the color of each customer, read from the database) *@
<HeadContent><style>@AstrolCustomTheme.GetCss(tenant.BrandColor)</style></HeadContent>
<!-- and data-aui-color="custom" on <html> -->
```

```css
/* CSS only: one variable is enough (the strong shade and the text color have defaults) */
:root { --aui-custom-brand: #0ea5e9; }

/* Or a named theme of your own: data-aui-color="acme" */
[data-aui-color="acme"] {
    --aui-brand: #0f766e;        /* buttons, focus, selection, active menu item */
    --aui-brand-strong: #115e59; /* hover and text over light backgrounds */
    --aui-on-brand: #ffffff;     /* text on top of the color */
}
```


---

# What's new

> What's new in AstrolUI for .NET 10: lighter and faster, notification and modal services, automatic mode, accessibility and migration guide.

Source page: https://doc.astrolui.com/whats-new

This release of **AstrolUI for .NET 10** is a full overhaul of **Astrol.Component.Basic** and its dependencies, focused on **performance**, **size**, **user experience** and **accessibility**. The **astrol-*** icon names do not change. Some changes break the previous API: the steps to migrate your projects are at the end of this page.

## 1. Lighter and faster

- **Global CSS**: from 220 KB in 4 chained files (with bootstrap) to **68 KB in a single file** (15 KB compressed).
- **interact.js** (126 KB) is no longer loaded: drag and resize are native and only downloaded when used.
- **Icons**: a **24 KB** core with the component icons and the most common ones; the rest (145 KB) is only downloaded when a page uses one.
- **On-demand JavaScript**: each component (modal, combo, editor…) loads its module only when it appears.
- **NuGet package** for Basic: from 1,921 KB to **347 KB**, now including the new components (tabs, checkbox, radio, dropdown, tooltip, alerts and badges). Details for each package in [Installation](/basic-component/installation).
- **Grid**: no longer copies the data or uses one component per cell. With 2,000 rows, re-rendering the page goes from 16 ms to **0.9 ms**, sorting from 476 ms to **47 ms** and filtering from 379 ms to **36 ms**.

## 2. New

- **IAstrolToast**: notifications from code (**Toast.Success("Saved")**), rendered by Blazor, pausing on hover and following the theme. [See Notification](/basic-component/notification).
- **IAstrolModal**: **await Modal.ConfirmAsync(...)** and **await Modal.ShowAsync<Component>(...)** with a result, without **@ref**. [See Confirm](/basic-component/confirm).
- **Automatic mode**: the theme follows the operating system light or dark mode and changes live; notifications and browser controls follow the theme too. [See Layout menu](/basic-component/layout-menu).
- **Grid**: typed **Field** and nested paths, **Format**, **Virtualize**, and column width is kept when paging. [See Grid](/basic-component/grid).
- **ComboBox**: **Display="p => p.Name"** and **@bind-Value**; opens upwards when there is no room and works inside grids and modals. [See ComboBox](/form/combo-box).
- **Modal** as a native **<dialog>**: always on top, Esc and focus handled by the browser.
- **Texts in the app language** (English or Spanish) and **AstrolText.Resolver** to translate into other languages.
- **GetColorContrast()**: picks the text color with the best contrast over a background.

```csharp
// Program.cs
builder.Services.AddAstrolBasic();

// Page or component
@inject IAstrolToast Toast
@inject IAstrolModal Modal

if (await Modal.ConfirmAsync("Are you sure?", "The item will be deleted."))
{
    await Delete(item);
    Toast.Success("Deleted");
}

var result = await Modal.ShowAsync<EditUser>("Edit", new Dictionary<string, object?> { ["Id"] = 5 });
if (!result.Cancelled) { var user = result.GetData<User>(); }
```

## 3. Accessibility and user experience

- Every control can be used with the **keyboard**: real buttons in modals, menu, paging, sortable headers and filters; the menu uses real links (Ctrl+click opens a new tab).
- **Visible focus** with the theme color when navigating with Tab.
- Screen reader labels (**aria-label**, **aria-sort**, **aria-expanded**, table roles, alerts).
- Respects the operating system **reduce motion** setting.
- **Security**: notifications and menu names are plain text by default (no HTML injection).

## 4. How to migrate a project

- **Program.cs**: replace **services.AddScoped<AstrolJSInterop>()** with **services.AddAstrolBasic()** (**using Astrol.Component.Basic;**).
- **index.html / _Host.cshtml**:
  - Remove **_content/Astrol.Component.Basic/js/interact.min.js** (if you use **Board**, change it to **_content/Astrol.Component.Board/js/interact.min.js**).
  - RichText paths move from **Astrol.Component.Basic** to **Astrol.Component.RichText**.
  - If your app uses **bootstrap** classes, reference bootstrap yourself.
  - Remove standalone links to **fontello.min.css** and **animation.min.css**: they are now inside **astrol-basic.min.css**.
- **Notifications with HTML**: they are now plain text. Replace **<br />** with **\n** or use **AllowHtml = true** with trusted content. Same for **MenuItem.Name** (**NameIsHtml = true**).
- **ConvertByteToMB()** now returns MB (it returned KB); use **ConvertBytesToKB()** for KB.
- **Grid**: if you used **<Columns Context="x">**, move **Context** to each **<Column>**; the **Load** parameter is gone.
- **Themes without AstrolLayoutMenu**: add **data-aui-color** and **data-aui-mode** where you set the class (e.g. **green-dark-mode**).
- **Custom CSS** on internal elements (**.head-astrol-modal i**, **.page-item a**, **#_pageInput**…): they are now buttons with classes; review your selectors.
- **Optional**: move from **jsI.Notification(...)** to **IAstrolToast** and from **<AstrolConfirm @ref>** to **IAstrolModal.ConfirmAsync**.

The full guide, with every change, how to detect it (regular expressions) and before/after examples, is in the repository at **docs/refactor/MIGRATION.md**; it is written so an AI can also apply it to your project.

```csharp
// ---- before ----
services.AddScoped<AstrolJSInterop>();
await jsI.Notification("Saved <br/> successfully".NotificationSuccess());
var ok = await _conf.Confirmation("Are you sure?", "Message"); // <AstrolConfirm @ref="_conf" />

// ---- now ----
services.AddAstrolBasic();
Toast.Success("Saved\nsuccessfully");
var ok = await Modal.ConfirmAsync("Are you sure?", "Message");
```

```html
<!-- before -->
<script src="_content/Astrol.Component.Basic/js/interact.min.js"></script>
<script src="_content/Astrol.Component.Basic/js/astrol-rich-text.min.js"></script>

<!-- now: interact is no longer needed (except with Board); RichText in its own package -->
<script src="_content/Astrol.Component.RichText/js/astrol-rich-text.min.js"></script>
```


---

# Checkbox

> AstrolCheckbox: Blazor checkbox on top of the native input, with @bind-Value, intermediate state, disabled state and EditForm validation.

Source page: https://doc.astrolui.com/form/checkbox

Checkbox with the theme look.

## 1. Demo AstrolCheckbox

```razor
@using Astrol.Component.Basic.Form

<AstrolCheckbox @bind-Value="remember" Text="Remember me" />
<AstrolCheckbox @bind-Value="news">I want to receive the <b>newsletter</b></AstrolCheckbox>
<AstrolCheckbox Value="true" Disabled="true" Text="Disabled" />

@* Select all: intermediate state (–) when only some are checked *@
<AstrolCheckbox Value="@allSelected" Indeterminate="@someSelected" ValueChanged="SelectAll" Text="All" />
@foreach (var key in items.Keys.ToList())
{
    var name = key;
    <AstrolCheckbox Value="@items[name]" ValueChanged="v => items[name] = v" Text="@name" />
}
@code {
```

```csharp
    private bool remember = true;
    private bool news;
    private readonly Dictionary<string, bool> items = new() { ["A"] = true, ["B"] = false, ["C"] = false };
    private bool allSelected => items.Values.All(v => v);
    private bool someSelected => items.Values.Any(v => v) && !allSelected;

    private void SelectAll(bool value)
    {
        foreach (var key in items.Keys.ToList()) items[key] = value;
    }
}
```

I want to receive the **newsletter**

## 2. Inside an EditForm

With **@bind-Value** inside an **EditForm**, the checkbox notifies validation of the change and turns red if it is invalid. Press Save without checking it.

```razor
<EditForm Model="terms" OnValidSubmit="Accept">
    <DataAnnotationsValidator />
    <AstrolCheckbox @bind-Value="terms.Accepted" Text="I accept the terms" />
    <ValidationMessage For="() => terms.Accepted" />
    <AstrolButton Type="ButtonType.Submit" Text="Save" />
</EditForm>

@code {
    private TermsModel terms = new();

    private sealed class TermsModel
    {
        [Range(typeof(bool), "true", "true", ErrorMessage = "Accept the terms to continue.")]
        public bool Accepted { get; set; }
    }
}
```

### Supported parameters

- Value **(bool)**, checked or not; binds with **@bind-Value**.
- Text **(string)** or ChildContent **(RenderFragment)**, text or content next to the box; clicking it also toggles.
- Indeterminate **(bool)**, intermediate state (–), e.g. "select all" with only some checked (default **false**).
- Disabled **(bool)**, disabled (default **false**).
- AriaLabel **(string)**, accessible text when there is no visible text.
- Id **(string)** and Class **(string)**; other attributes (**name**, **title**...) go to the input.

It is a native **<input type="checkbox">**: it works with the keyboard (Space), screen readers and forms. AstrolGrid uses it to select rows.


---

# ComboBox

> AstrolComboBox is an interactive component that combines a text box with a dropdown list, allowing you to select an option from a variety of elements. Whether it's for filtering options, facilitating data entry, or providing contextual selections, AstrolComboBox stands as an elegant solution to enhance the user experience, offering flexibility and efficiency in interaction.

Source page: https://doc.astrolui.com/form/combo-box

## 1. Demo AstrolComboBox

```razor
@using Astrol.Component.Basic.Form
<AstrolLabel TItem="Person" For="@nameof(Person.Name)" />
<AstrolComboBox HasContentInput="true"
                ShowOpenIcon="true"
                TItem="Person"
                Placeholder="Search for a person"
                Id="@nameof(Person.Name)"
                Display="p => p.Name"
                @bind-Value="person"
                NoSearchResultText="No results found"
                DataList="list" />
<div><b>Id: </b>@person?.Id</div>
<div><b>Name: </b>@person?.Name</div>
<div><b>Age: </b>@person?.Age</div>
<div><b>Sex: </b>@person?.Sex</div>
@code {
```

```csharp
   private Person? person;
   List<Person> list = new List<Person> {
       new Person { Id = 1, Name = "Juan", Age = 25, Sex = true },
       new Person { Id = 2, Name = "Ana", Age = 30, Sex = false },
       new Person { Id = 3, Name = "Pedro", Age = 42, Sex = true },
       new Person { Id = 4, Name = "María", Age = 19, Sex = false },
       new Person { Id = 5, Name = "Carlos", Age = 55, Sex = true }
   };
   public class Person {
       public int Id { get; set; }
       public string Name { get; set; } = string.Empty;
       public int Age { get; set; }
       public bool Sex { get; set; }
   }
}
```

### Supported parameters

- TItem **(object)**, option type **(required)**.
- DataList **(IEnumerable<TItem>)**, options to display.
- Display **(Func<TItem, string?>)**, text of each option, e.g. **Display="p => p.Name"(recommended)**.
- PropertyShow **(string)**, alternative to Display using the property name (supports "A.B" paths).
- Value **(TItem)** / **ValueChanged**, selected item; supports **@bind-Value**.
- InitialValue **(TItem)**, initial value without two-way binding.
- OnChange **(EventCallback<ChangeEventArgs>)**, raised when the selection changes; **Value** holds the item or null.
- Filtrable **(bool)**, filters while typing, ignoring case and accents (default **true**).
- Placeholder **(string)**, input placeholder.
- HasContentInput **(bool)**, uses the **AstrolContentInput** container (default **false**).
- ShowOpenIcon **(bool)**, shows the open icon on the right, **only if HasContentInput is true** (default **false**).
- PropertyShowIsHtml **(bool)**, option text is HTML. **Trusted content only**: it is inserted unescaped.
- NoSearchResultText **(string)**, text when there are no results (default follows the app language).
- Id **(string)** and Class **(string)**, HTML id and css class.
- The selection is compared with **Equals**: **Value** / **InitialValue** must be an instance from **DataList** (or TItem must override Equals, e.g. a **record**).
- When **Filtrable** is **false** the input is read-only. Typing text that exactly matches an option selects it; on leaving the field, if the text does not match the selection, both the text and the selection are cleared.
- Methods (via **@ref**): **ChangeValue(item)** selects an item from code and **ChangeDataList(list, selected)** replaces the options (and optionally the selection).
- Keyboard: **arrows** to move, **Enter** to select and **Esc** to close. The dropdown opens upwards when there is no room below and works inside grids and modals.


---

# ContentInput

> AstrolContentInput wraps an input, textarea or select (also InputText, InputSelect...) and gives it the AstrolUI look: border, height, hover and a focus ring in the theme color, with an optional icon button.

Source page: https://doc.astrolui.com/form/content-input

Gives your own fields the AstrolUI look and adds an action button to them.

## 1. What it is for

AstrolUI **does not change your app's fields**: a bare **<input>** looks the way the browser draws it. **AstrolContentInput** is the wrapper that gives them the AstrolUI look: same height as the buttons (38 px), theme border and radius, a stronger border on hover and a **focus ring** in the theme color while typing. It works with **input**, **textarea**, **select** and Blazor's components (**InputText**, **InputNumber**, **InputSelect**, **InputTextArea**...).

Click the fields in each column to see the difference:

Without AstrolContentInput

```razor
@using Astrol.Component.Basic.Form

@* Without the wrapper: the browser's own field *@
<input type="text" placeholder="Name" />

@* With the wrapper: AstrolUI look (border, height, radius, hover and focus ring in the theme color) *@
<AstrolContentInput>
    <input type="text" placeholder="Name" />
</AstrolContentInput>
<AstrolContentInput>
    <textarea placeholder="Comment"></textarea>
</AstrolContentInput>
```

## 2. Icon button inside the field

With **Icon** a button appears on the right of the field (the text leaves room for it) and **OnClickIcon** runs when it is pressed: clear, search, call, copy... Set **IconAriaLabel** for screen readers. **AstrolInputPassword** uses this same button to show or hide the password.

```razor
<AstrolContentInput Icon="astrol-cancel" IconAriaLabel="Clear" OnClickIcon="() => name = string.Empty">
    <input type="text" placeholder="Name" @bind="name" @bind:event="oninput" />
</AstrolContentInput>
<AstrolContentInput Icon="astrol-phone" IconAriaLabel="Call" OnClickIcon="Call">
    <input type="tel" placeholder="Phone" @bind="phone" />
</AstrolContentInput>
```

## 3. Inside an EditForm

Wrap Blazor's form components just like an input. When validation marks the field as **invalid**, the border turns red. **FocusRing="false"** removes the focus ring and **HasShadow="false"** the shadow, for quieter fields. Submit the empty form to see validation.

```razor
<EditForm Model="contact" OnValidSubmit="Save">
    <DataAnnotationsValidator />
    <AstrolContentInput>
        <InputText @bind-Value="contact.Email" placeholder="Email" />
    </AstrolContentInput>
    <ValidationMessage For="() => contact.Email" />
    <AstrolContentInput>
        <InputSelect @bind-Value="contact.Topic"> ... </InputSelect>
    </AstrolContentInput>
    <AstrolContentInput FocusRing="false" HasShadow="false">
        <InputTextArea @bind-Value="contact.Message" />
    </AstrolContentInput>
    <AstrolButton Type="ButtonType.Submit" Text="Save" Icon="astrol-floppy" />
</EditForm>
```

## 4. No wrapper: aui-input and aui-textarea classes

If you don't need the icon button, put the **aui-input** (or **aui-textarea**) class directly on the field and it gets the same look.

```razor
@* Same look without the wrapper (no icon button and no extra margin) *@
<input class="aui-input" placeholder="Search" />
<textarea class="aui-textarea"></textarea>
<InputText class="aui-input" @bind-Value="model.Name" />
```

### Supported parameters

- ChildContent **(RenderFragment)**, field to wrap: **input**, **textarea**, **select** or a Blazor component (**InputText**, **InputSelect**...).
- Icon **(string)**, icon of the button shown on the right of the field (**optional**).
- OnClickIcon **(EventCallback)**, runs when the icon button is pressed.
- IconAriaLabel **(string)**, accessible text of the icon button (defaults to the app's language).
- FocusRing **(bool)**, focus ring in the theme color and stronger border on hover (default **true**). It used to be called **ShowEffect**.
- HasShadow **(bool)**, soft shadow on the field (default **true**).
- Class **(string)**, extra css class for the wrapper.


---

# InputPassword

> AstrolInputPassword focuses on privacy and security by hiding characters while the user types. By providing an additional level of confidentiality, it is ideal for forms and authentication processes where protecting sensitive information is paramount.

Source page: https://doc.astrolui.com/form/inputs-password

## 1. Demo AstrolInputPassword using EditForm

In this example, [notifications](/basic-component/notification), [buttons](/basic-component/button), [labels](/form/label), and [content inputs](/form/content-input) are implemented. It is recommended to refer to the documentation for each of them.

```razor
@using Astrol.Component.Basic.Button
@using Astrol.Component.Basic.Form
@using System.ComponentModel.DataAnnotations
@using Astrol.Entities.Basic.Static.Notification
@using Astrol.Entities.Basic.UI
@using Astrol.JSInterop.Base
@inject AstrolJSInterop jsI

<EditForm Model="@login" OnValidSubmit="@HandleValidSubmit">
   <DataAnnotationsValidator />
   <div class="form-control-file">
       <AstrolLabel TItem="Login" For="@nameof(login.Password)" />
       <AstrolInputPassword @bind-Value="@login.Password" Id="@nameof(login.Password)" Class="form-control"/>
       <ValidationMessage For="@(() => login.Password)" />
   </div>
   <AstrolButton Type="ButtonType.Submit" Text="Send" Style="AstrolStyle.Blue" Class="fr" />
</EditForm>
@code {
```

```csharp
   public class Login {
       [Display(Name = "Password")]
       [Required(ErrorMessage = "Password required.")]
       [MinLength(6, ErrorMessage = "Minimum length of 6 characters.")]
       public string Password { get; set; } = string.Empty;
   }
   private Login login = new Login();
   private async Task HandleValidSubmit() {
       await jsI.Notification("Sending form".NotificationSuccess("astrol-ok"));
   }
}
```

### Supported parameters

- Value **(string)**, the password; bind it with **@bind-Value(required)**. It inherits **InputBase<string>**: inside an **EditForm** it takes part in validation (**DataAnnotationsValidator**, **ValidationMessage**).
- Id **(string)**, HTML id of the input (to link a label).
- Class **(string)**, extra css class for the input.
- Placeholder **(string)**, input placeholder.
- ShowPassword **(bool)**, shows the password initially; the user can toggle it with the lock icon (default **false**).
- Autocomplete **(bool)**, allows browser autocomplete; with **false** it uses **autocomplete="new-password"** (default **true**).
- IconAriaLabel **(string)**, accessible text of the show/hide button (default follows the app language).
- HasShadow **(bool)** and FocusRing **(bool)**, shadow and effect of the **AstrolContentInput** container (default **true**).
- Other attributes (e.g. **maxlength**, **required**, **autofocus**) are applied to the input.


---

# Label

> AstrolLabel is an essential component in the user interface, designed to provide descriptive information and enhance the understanding of associated elements.

Source page: https://doc.astrolui.com/form/label

## 1. Demo AstrolLabel

```razor
@using Astrol.Component.Basic.Form
@using System.ComponentModel.DataAnnotations

<!-- Text from [Display(Name)]; clicking the label focuses the input with the same id -->
<AstrolLabel TItem="Login" For="@nameof(login.Password)" />
<input id="@nameof(login.Password)" type="password" class="aui-input" />

<!-- Typed expression and custom text -->
<AstrolLabel TItem="Login" ForExpression="x => x.User" Text="E-mail" />
<input id="@nameof(login.User)" type="email" class="aui-input" />
@code {
```

```csharp
   public class Login {
       public string User { get; set; } = string.Empty;
       [Display(Name = "Password")]
       public string Password { get; set; } = string.Empty;
   }
   private Login login = new Login();
}
```

### Supported parameters

- TItem **(T)**, model whose property is described **(required)**.
- For **(string)**, name of the TItem property; it is also used as the label's **for** attribute, so the input must have an **id** equal to that name, e.g. **For="@nameof(Login.Password)"**.
- ForExpression **(Expression<Func<TItem, object?>>)**, typed alternative to For, e.g. **ForExpression="x => x.Password"**; used only when For is empty.
- Text **(string)**, label text; when not set, the **Name** of the property's **[Display]** attribute is used, or the **property name** if there is none.
- ChildContent **(RenderFragment)**, custom label content; when set, **Text is ignored**.


---

# Radio

> AstrolRadioGroup and AstrolRadio: Blazor radio options on top of the native input, of any type, in a column or a row, with @bind-Value and EditForm validation.

Source page: https://doc.astrolui.com/form/radio

One option among several, with the theme look.

## 1. Demo AstrolRadioGroup

**AstrolRadioGroup** holds the chosen value and each **AstrolRadio** is an option with its **Value**. The type is inferred (text, numbers, enums...). With focus on an option, the arrows change the option.

```razor
@using Astrol.Component.Basic.Form

<AstrolRadioGroup @bind-Value="payment" AriaLabel="Payment method">
    <AstrolRadio Value="@("card")" Text="Card" />
    <AstrolRadio Value="@("transfer")" Text="Bank transfer" />
    <AstrolRadio Value="@("cash")" Text="Cash" Disabled="true" />
</AstrolRadioGroup>

@* Any type: enums, numbers, objects... In a row with Horizontal *@
<AstrolRadioGroup @bind-Value="theme" Horizontal="true" AriaLabel="Theme">
    @foreach (var item in Enum.GetValues<AstrolThemeMode>())
    {
        <AstrolRadio Value="item" Text="@item.ToString()" />
    }
</AstrolRadioGroup>
@code {
```

```csharp
    private string? payment = "card";
    private AstrolThemeMode theme = AstrolThemeMode.Auto;
}
```

### Supported parameters

**AstrolRadioGroup<TValue>**

- Value **(TValue)**, chosen value; binds with **@bind-Value** (validated inside an **EditForm**).
- Horizontal **(bool)**, options in a row (default **false**, in a column).
- Disabled **(bool)**, disables every option.
- Name **(string)**, **name** attribute of the inputs (default: a unique one per group).
- AriaLabel **(string)**, the group's question for screen readers.
- Class **(string)**, extra css class.

**AstrolRadio<TValue>**

- Value **(TValue)**, value of the option.
- Text **(string)** or ChildContent **(RenderFragment)**, option text or content.
- Disabled **(bool)**, disabled option.
- Id **(string)** and Class **(string)**; other attributes go to the input.


---

# Toggle

> AstrolToggle is an accessible switch to turn an option on or off with a click or from the keyboard.

Source page: https://doc.astrolui.com/form/toggle

## 1. Demo AstrolToggle

```razor
@using Astrol.Component.Basic.Form

<label for="toggle-login">Remember me (@(value ? "Yes" : "No"))</label>
<AstrolToggle Id="toggle-login" @bind-Value="value" />

<label for="toggle-disabled">Disable</label>
<AstrolToggle Id="toggle-disabled" Value="true" Disable="true" />
@code {
```

```csharp
   private bool value = true;
}
```

### Supported parameters

- Value **(bool)** / **ValueChanged**, switch state (default **false**); supports **@bind-Value**.
- OnChange **(EventCallback<bool>)**, raised when the state changes, with the new value.
- Object **(object)**, associated object returned in **OnChangeObject** (useful in lists or grids).
- OnChangeObject **(EventCallback<(object?, bool)>)**, raised when the state changes, with the associated object and the new value.
- Disable **(bool)**, disables the switch (default **false**).
- Id **(string)**, HTML id of the button; lets you link a **<label for="...">**.
- LabelledBy **(string)**, id of the element that gives it its accessible name (**aria-labelledby**).
- It renders as a **<button role="switch">**: it is activated by click, **Space** or **Enter**. Always give it an accessible name with a label (**Id**) or with **LabelledBy**.


---

# Alert

> AstrolAlert: in-page Blazor messages with a status (info, success, warning, error, brand), title, actions and close button; accessible with role alert or status.

Source page: https://doc.astrolui.com/basic-component/alert

In-page messages: information, success, warning or error.

## 1. Demo AstrolAlert

Unlike notifications, an alert stays on the page until the situation changes (or the user closes it with **Closable**). Error and warning alerts are announced right away to screen readers.

```razor
@using Astrol.Component.Basic.Alert

<AstrolAlert Text="Your trial ends in 5 days." />
<AstrolAlert Status="AstrolStatus.Success" Title="Saved" Text="The customer was updated." Closable="true" />
<AstrolAlert Status="AstrolStatus.Warning" Text="Some fields are empty." />
<AstrolAlert Status="AstrolStatus.Danger" Title="Could not save" Text="The server did not respond.">
    <Actions>
        <AstrolButton Text="Retry" Icon="astrol-arrows-cw" Style="AstrolStyle.Red" />
        <AstrolButton Text="Details" Style="AstrolStyle.White" />
    </Actions>
</AstrolAlert>
<AstrolAlert Status="AstrolStatus.Brand" Icon="astrol-flash" Text="New: tabs, checkboxes and radios." />
```

Your trial ends in 5 days.

The customer was updated.

Some fields of the form are empty.

The server did not respond. Check your connection.

New: tabs, checkboxes and radios.

### Supported parameters

- Status **(AstrolStatus)**, **Info** (default), **Success**, **Warning**, **Danger**, **Brand** or **Neutral**: color and icon.
- Title **(string)**, bold title (optional).
- Text **(string)** or ChildContent **(RenderFragment)**, the message.
- Actions **(RenderFragment)**, buttons or links below the message.
- Icon **(string)**, own icon; ShowIcon **(bool)**, show the icon (default **true**).
- Closable **(bool)**, close button; OnClose **(EventCallback)** when closed; CloseText **(string)**; **Show()** shows it again.
- Class **(string)**, extra css class.


---

# Assign

> AstrolAssign is a component with a two-column interface that represents two sets of items. Users can move items between the columns with the action buttons in the center of the component. It is ideal for assigning items or changing their state intuitively, and is commonly used to manage resources, tasks or data between two sets.

Source page: https://doc.astrolui.com/basic-component/assign

## 1. Demo AstrolAssign

The component can receive any type of object list in its **UnAssignedList** and **AssignedList** properties. For this, it is **mandatory** to represent one of the properties in the component using the **PropertyShow** parameter.

You can also specify, if desired, that your object has a **unique property** that is **not displayed** but is used for **internal processing**. For this purpose, the **PropertyUnique** parameter is used.

The **PropertyUnique parameter is not required**, but if not specified, it **assumes that the PropertyShow parameter is unique**.

The **x/y** counter of each column selects or deselects all filtered items.

```razor
@using Astrol.Component.Basic.Assign
<AstrolAssign TItem="Person"
              Height="300px"
              UnAssignedList="unAssignedList"
              AssignedList="assignedList"
              PropertyShow="@nameof(Person.Name)"
              PropertyUnique="@nameof(Person.Id)"
              UnAssignedTitle="Not assigned"
              AssignedTitle="Assigned"
              PlaceholderInputSearch="Search..."
              OnChange="HandleMyEvent" />
@code {
```

```csharp
   List<Person> assignedList = new List<Person>();
   List<Person> unAssignedList = new List<Person>()
   {
       new Person() { Id = 1, Name = "Juan", Age = 25, Sex = true },
       new Person() { Id = 2, Name = "María", Age = 30, Sex = false },
       new Person() { Id = 3, Name = "Pedro", Age = 40, Sex = true },
       new Person() { Id = 4, Name = "Ana", Age = 35, Sex = false },
       new Person() { Id = 5, Name = "Luis", Age = 28, Sex = true },
   };
   private void HandleMyEvent((List<Person>, List<Person>) items)
   {
       unAssignedList = items.Item1;
       assignedList = items.Item2;
   }
   public class Person
   {
       public int Id { get; set; }
       public string Name { get; set; }
       public int Age { get; set; }
       public bool Sex { get; set; }
   }
}
```

### Supported parameters

- **TItem** (generic type): object, entity or model of the items in both lists.
- **UnAssignedList** (List<TItem>?): unassigned items (left column). The component modifies it in place when items are moved.
- **AssignedList** (List<TItem>?): assigned items (right column). The component modifies it in place when items are moved.
- **PropertyShow** (string): name of the TItem property displayed in both columns and used by the search (case-insensitive). If not set or not found, the item's **ToString()** is displayed.
- **PropertyUnique** (string?): name of the TItem property that uniquely identifies each item (internal use, not displayed). Not required; if not set or not found, **PropertyShow** is used as the identifier.
- **UnAssignedTitle** (string?): title of the unassigned column. If not set, it follows the app language (**Unassigned** / **No asignados**).
- **AssignedTitle** (string?): title of the assigned column. If not set, it follows the app language (**Assigned** / **Asignados**).
- **PlaceholderInputSearch** (string?): placeholder of both search inputs. If not set, it follows the app language (**Search** / **Buscar**).
- **BorderRadius** (string?): border radius of both columns (default: the theme radius, **12px**).
- **Height** (string?): height of the component (default is **300px**).
- **Outline** (bool): shows the column headers with a light style (gray background, dark text) instead of the theme color (default is **false**). Only applied when the component is initialized.
- **OnChange** (EventCallback<(List<TItem>, List<TItem>)>): raised every time items are assigned, unassigned or exchanged. It receives a tuple: **Item1** is the unassigned list and **Item2** the assigned list.
- **Refresh()** (public method): clears the selections and re-applies the filters. Call it through **@ref** if you change the lists from outside the component.
- Keyboard: items and the center buttons are activated with **Enter** or **Space**.


---

# Badge

> AstrolBadge: Blazor status labels (active, pending, blocked...) colored by meaning, with an icon or a dot, and an outline variant.

Source page: https://doc.astrolui.com/basic-component/badge

Short status labels or counters.

## 1. Demo AstrolBadge

The color comes from **Status** (the same **AstrolStatus** as **AstrolAlert**); **Brand** uses the theme color. Use them in tables, cards or next to a title.

```razor
@using Astrol.Component.Basic.Badge

@foreach (var status in Enum.GetValues<AstrolStatus>())
{
    <AstrolBadge Status="status" Text="@status.ToString()" />
}

<AstrolBadge Status="AstrolStatus.Success" Dot="true" Text="Active" />
<AstrolBadge Status="AstrolStatus.Warning" Dot="true" Text="Pending" />
<AstrolBadge Status="AstrolStatus.Danger" Icon="astrol-cancel" Text="Blocked" Outline="true" />
<AstrolBadge Status="AstrolStatus.Brand" Icon="astrol-star" Text="Pro" />
<AstrolBadge Text="12" Title="Unread messages" />
```

### Supported parameters

- Text **(string)** or ChildContent **(RenderFragment)**, the text.
- Status **(AstrolStatus)**, **Neutral** (default), **Brand**, **Info**, **Success**, **Warning** or **Danger**.
- Icon **(string)**, icon before the text; Dot **(bool)**, a colored dot instead.
- Outline **(bool)**, border only, no background (default **false**).
- Title **(string)**, text on hover; Class **(string)**.


---

# Box

> AstrolBox is a rectangular Blazor component that can contain other elements, such as text, images or forms. It is commonly used to organize and structure the web layout.

Source page: https://doc.astrolui.com/basic-component/box

## 1. Demo AstrolBox

```razor
@using Astrol.Entities.Basic.UI
@using Astrol.Component.Basic.Box
<AstrolBox Style="AstrolStyle.Base">Base</AstrolBox>
<AstrolBox Style="AstrolStyle.White">White</AstrolBox>
<AstrolBox Style="AstrolStyle.Black">Black</AstrolBox>
<AstrolBox Style="AstrolStyle.Blue">Blue</AstrolBox>
<AstrolBox Style="AstrolStyle.Green">Green</AstrolBox>
<AstrolBox Style="AstrolStyle.Orange">Orange</AstrolBox>
<AstrolBox Style="AstrolStyle.Red">Red</AstrolBox>
<AstrolBox Style="AstrolStyle.Yellow">Yellow</AstrolBox>
<AstrolBox Style="AstrolStyle.Purple">Purple</AstrolBox>
<!-- Outline -->
<AstrolBox Style="AstrolStyle.Base" Outline="true">Base</AstrolBox>
<AstrolBox Style="AstrolStyle.White" Outline="true">White</AstrolBox>
<AstrolBox Style="AstrolStyle.Black" Outline="true">Black</AstrolBox>
<AstrolBox Style="AstrolStyle.Blue" Outline="true">Blue</AstrolBox>
<AstrolBox Style="AstrolStyle.Green" Outline="true">Green</AstrolBox>
<AstrolBox Style="AstrolStyle.Orange" Outline="true">Orange</AstrolBox>
<AstrolBox Style="AstrolStyle.Red" Outline="true">Red</AstrolBox>
<AstrolBox Style="AstrolStyle.Yellow" Outline="true">Yellow</AstrolBox>
<AstrolBox Style="AstrolStyle.Purple" Outline="true">Purple</AstrolBox>
<!-- Custom content -->
<AstrolBox Style="AstrolStyle.Green" Outline="true">
   <h1>
       <Astrol.Component.Basic.Icon.AstrolIcon Icon="astrol-emo-sunglasses" />
       Hello World!
   </h1>
</AstrolBox>
```

## Hello World!

### Supported parameters

- **ChildContent** (RenderFragment?): HTML content of the box.
- **Style** (AstrolStyle): color of the box (default is **AstrolStyle.Base**).
  - **Base** (enum)
  - **White** (enum)
  - **Black** (enum)
  - **Red** (enum)
  - **Orange** (enum)
  - **Green** (enum)
  - **Blue** (enum)
  - **Yellow** (enum)
  - **Purple** (enum)
- **Outline** (bool): shows the box without fill, only with the border and text in the chosen color (default is **false**).
- **BorderRadius** (string): border radius of the box (default: the theme radius, **6px**).
- **Class** (string?): additional CSS class (not required).
- **AdditionalClasses** (IEnumerable<string>?): additional CSS classes added together with **Class** (not required).
- **OnClick** (EventCallback<MouseEventArgs>): action when the box is clicked (not required). The box is a **div**: it cannot receive focus or be activated with the keyboard, so use **AstrolButton** for actions.


---

# Breadcrumb

> AstrolBreadcrumb is a Blazor component for visual navigation that displays the user's path to the current page.

Source page: https://doc.astrolui.com/basic-component/breadcrumb

## 1. Demo AstrolBreadcrumb

```razor
@using Astrol.Entities.Basic.UI
@using Astrol.Component.Basic.Breadcrumb
<AstrolBreadcrumb BreadcrumbList="BreadcrumbList" />
@code {
```

```csharp
   private List<BreadcrumbItem> BreadcrumbList = new List<BreadcrumbItem> {
       new BreadcrumbItem { Text = "Home", Icon = "astrol-home", URL = "/"},
       new BreadcrumbItem { Text = "Components", Icon = "astrol-th-outline", URL = "/basic-component"},
       new BreadcrumbItem { Text = "Breadcrumb"},
   };
}
```

### Supported parameters

- **BreadcrumbList** (List<BreadcrumbItem>): items to display, in order. If it is null or empty nothing is displayed.
- **Separator** (string): class of the separator icon between items (default is **astrol-angle-right** *).
- **BreadcrumbItem** properties (Astrol.Entities.Basic.UI):
  - **URL** (string?): link address. The last item is always displayed as text (current page, with aria-current="page") even if it has a URL; items without a URL are also displayed as text.
  - **Text** (string?): item text.
  - **Icon** (string?): class of the icon before the text (not required).


---

# Button

> AstrolButton is an essential Blazor component in applications and websites, providing a clear and visually prominent way for users to initiate actions or processes.

Source page: https://doc.astrolui.com/basic-component/button

## 1. Demo AstrolButton

```razor
@using Astrol.Entities.Basic.UI
@using Astrol.Component.Basic.Button
<AstrolButton Text="Button 1" />
<AstrolButton Text="Button 2" Style="AstrolStyle.White" />
<AstrolButton Text="Button 3" Style="AstrolStyle.Black" />
<AstrolButton Text="Button 4" Style="AstrolStyle.Blue" />
<AstrolButton Text="Button 5" Style="AstrolStyle.Green" />
<AstrolButton Text="Button 6" Style="AstrolStyle.Orange" />
<AstrolButton Text="Button 7" Style="AstrolStyle.Red" />
<AstrolButton Text="Button 8" Style="AstrolStyle.Yellow" />
<AstrolButton Text="Button 9" Style="AstrolStyle.Purple" />
<br />
<AstrolButton Text="Button 1" Outline="true" />
<AstrolButton Text="Button 2" Style="AstrolStyle.White" Outline="true" />
<AstrolButton Text="Button 3" Style="AstrolStyle.Black" Outline="true" />
<AstrolButton Text="Button 4" Style="AstrolStyle.Blue" Outline="true" />
<AstrolButton Text="Button 5" Style="AstrolStyle.Green" Outline="true" />
<AstrolButton Text="Button 6" Style="AstrolStyle.Orange" Outline="true" />
<AstrolButton Text="Button 7" Style="AstrolStyle.Red" Outline="true" />
<AstrolButton Text="Button 8" Style="AstrolStyle.Yellow" Outline="true" />
<AstrolButton Text="Button 9" Style="AstrolStyle.Purple" Outline="true" />
<br />
<AstrolButton Text="Button 1" Style="AstrolStyle.Blue" Icon="astrol-plus" />
<AstrolButton Text="Button 2" Style="AstrolStyle.Red" Icon="astrol-cancel" Outline="true" />
<AstrolButton Text="Button 3" Style="AstrolStyle.Green" Icon="astrol-spin5" AnimateIcon="true" />
<AstrolButton Text="Button 4" Style="AstrolStyle.Orange" Icon="astrol-spin4" AnimateIcon="true" Outline="true" />
```

### Supported parameters

- **Text** (string?): button text (optional).
- **Icon** (string?): class of the button icon (optional).
- **AnimateIcon** (bool): spins the icon when there is one (default is **false**).
- **Title** (string?): HTML title attribute (tooltip). Recommended for icon-only buttons (optional).
- **Class** (string?): CSS class to customize styles (optional).
- **Form** (string?): HTML form attribute: id of the form the button belongs to when placed outside it (optional).
- **OnClick** (EventCallback<MouseEventArgs>): button action; it runs immediately on every click. To avoid double submissions, disable the button (**Status="false"**) while it is processing.
- **BorderRadius** (string): border radius (default: the theme radius, **8px**).
- **Outline** (bool): button without fill, only with the border and text in the chosen color (default is **false**).
- **Status** (bool): whether the button is enabled; with **false** it is disabled (default is **true**).
- **Autofocus** (bool): the button receives focus when first rendered (also inside a modal); only if **Status** is true (default is **false**).
- **Type** (ButtonType): button type (default is **ButtonType.Button**).
  - **Button** (enum)
  - **Submit** (enum)
  - **Reset** (enum)
- **Style** (AstrolStyle): button style (default is **AstrolStyle.Base**).
  - **Base** (enum)
  - **White** (enum)
  - **Black** (enum)
  - **Red** (enum)
  - **Orange** (enum)
  - **Green** (enum)
  - **Blue** (enum)
  - **Yellow** (enum)
  - **Purple** (enum)


---

# Confirm

> AstrolConfirm is the Blazor component that allows obtaining user confirmation before performing a critical or irreversible action.

Source page: https://doc.astrolui.com/basic-component/confirm

## 1. Demo AstrolConfirm

In this example, [notifications](/basic-component/notification) and [buttons](/basic-component/button) are implemented, so it is recommended to refer to their documentation for more details.

```razor
@using Astrol.JSInterop.Base
@inject AstrolJSInterop jsI
@using Astrol.Entities.Basic.UI
@using Astrol.Component.Basic.Button
@using Astrol.Component.Basic.Confirm
@using Astrol.Entities.Basic.Static.Notification

<AstrolConfirm @ref="_conf" />
<AstrolButton Icon="astrol-trash-empty" Text="Delete" Style="@AstrolStyle.Red" OnClick="DeleteItem" />
@code {
```

```csharp
   private AstrolConfirm _conf = default!;
   private async Task DeleteItem() {
       var confirmed = await _conf.Confirmation("Are you sure?", "Do you want to delete the item?");
       if (confirmed) {
            await jsI.Notification("Item removed successfully.".NotificationSuccess());
       }
       else {
           await jsI.Notification("Canceled action.".NotificationError());
       }
   }
}
```

### Usage details

- **Recommended**, with the service: **@inject IAstrolModal Modal** and **if (await Modal.ConfirmAsync("Title", "Message")) { ... }**. No component in the page and no **@ref** needed; options with **new ConfirmOptions { ... }**.
- With the component: place **<AstrolConfirm @ref="_conf" />** in your page with a field **private AstrolConfirm _conf;** and call **await _conf.Confirmation("Title", "Message");**, which returns **true** when accepted:
  - **Title** (string) message title.
  - **Message** (string) confirmation message.
- When it opens, focus is on **Accept** (Enter confirms) and **Esc** cancels.

### Supported parameters

- Draggable **(bool)**, the window can be moved (default **true**).
- ClosedInteractive **(bool)**, cancels when clicking outside or pressing **Esc** (default **true**).
- Class **(string)**, custom css class.
- Icon **(string)**, icon (default astrol-question-circle-o**).
- ButtonOutline **(bool)**, buttons without fill (default **false**).
- TextAccept / TextCancel **(string)**, button texts (default follows the app language).
- Width **(AstrolWidth)**, max width: Mini (300px), **Short (450px, default)**, Middle (768px), Large (1200px), Full (100%).
- Calling **Confirmation** while another confirmation is open makes the previous one return **false**.
- The same options exist in **ConfirmOptions** for **IAstrolModal.ConfirmAsync**.


---

# Dropdown

> AstrolDropdown: Blazor actions menu with icons, shortcuts, disabled or dangerous options, links, separators and keyboard support; grids and modals don't clip it.

Source page: https://doc.astrolui.com/basic-component/dropdown

Button that opens a menu of actions.

## 1. Demo AstrolDropdown

With **Text** it is a secondary button with an arrow; without text it is a quiet icon button («⋮»), ideal at the end of a row or a card. The menu is painted in the browser's top layer, so grids, modals and scrolling containers don't clip it. Keyboard: Enter, Space or Arrow down open it, the arrows move through the options and Esc closes it.

```razor
@using Astrol.Component.Basic.Dropdown

<AstrolDropdown Text="Actions" Icon="astrol-cog" Align="AstrolDropdownAlign.Start">
    <AstrolDropdownItem Text="Edit" Icon="astrol-pencil" Shortcut="Ctrl+E" OnClick="Edit" />
    <AstrolDropdownItem Text="Duplicate" Icon="astrol-clone" OnClick="Duplicate" />
    <AstrolDropdownItem Text="Archive" Icon="astrol-archive" Disabled="true" />
    <AstrolDropdownSeparator />
    <AstrolDropdownItem Text="Delete" Icon="astrol-trash" Danger="true" OnClick="Delete" />
</AstrolDropdown>

@* Without Text: icon-only button (⋮), e.g. at the end of a row. AriaLabel names it. *@
<AstrolDropdown AriaLabel="Row actions">
    <AstrolDropdownItem Text="View" Icon="astrol-eye" OnClick="View" />
    <AstrolDropdownItem Text="Send email" Icon="astrol-mail" Href="mailto:juan@example.com" />
    <AstrolDropdownSeparator Title="Danger zone" />
    <AstrolDropdownItem Text="Delete" Icon="astrol-trash" Danger="true" OnClick="Delete" />
</AstrolDropdown>
```

### Supported parameters

**AstrolDropdown**

- Text **(string)**, button text; without text the button is just an icon.
- Icon **(string)**, button icon (without text, default **astrol-ellipsis-vert**).
- AriaLabel **(string)**, accessible text of the button and the menu (required for icon-only; default "More actions").
- Align **(AstrolDropdownAlign)**, **End** (default) aligns the menu with the button's right edge; **Start**, with the left one.
- ShowChevron **(bool)**, arrow next to the text (default **true**).
- Disabled **(bool)**, Class and ButtonClass **(string)**.
- OnToggle **(EventCallback<bool>)**, when it opens (true) and closes (false); **IsOpen**, **OpenAsync()** and **CloseAsync()** from code.

**AstrolDropdownItem**

- Text **(string)** or ChildContent, Icon **(string)** and Shortcut **(string)**, e.g. "Ctrl+E".
- OnClick **(EventCallback)**, or Href **(string)** and Target to make it a link.
- Disabled **(bool)**, Danger **(bool)** (in red) and KeepOpen **(bool)** (doesn't close the menu).

**AstrolDropdownSeparator**: line between groups; with **Title**, also a group title.


---

# .NET extensions

> C# extension methods included in AstrolUI: accent-insensitive search, slugs, money, file sizes, relative time, paging and sorting for EF Core, color contrast and more.

Source page: https://doc.astrolui.com/basic-component/extensions

Astrol.Entities.Basic: extension methods for text, numbers, dates, AstrolGrid queries, colors, enums and JSON.

**Astrol.Entities.Basic** is installed with Astrol.Component.Basic and brings extension methods for what almost every app repeats: cleaning and searching text, showing amounts and dates, paging on the server or picking a readable text color. They all accept **null** and never throw on an empty value. They are plain C#: they work the same in Blazor, an API or a service.

```razor
@* Installed with Astrol.Component.Basic (package Astrol.Entities.Basic) *@
@using Astrol.Entities.Basic.Static.Extensions
@using Astrol.Entities.Basic.Static   @* Auxiliar.NewKey(), Auxiliar.NewDomId() *@
```

## 1. Text

**ToSearchKey** lowercases the text, removes accents and ñ and leaves a single space between words: compare two keys and search works whether the user types «configuracion» or «CONFIGURACIÓN» (AstrolComboBox uses it this way). **ContainsIgnoreAccents** does it in one call. There are also URL slugs, avatar initials, title-cased names, truncation with «…», email and file-extension validation.

Type in the demo to see the result of each method.

```csharp
// Search without accents or case (filters, combos, lists)
var term = search.ToSearchKey();                       // "  Árbol " -> "arbol"
var result = clients.Where(c => c.Name.ContainsIgnoreAccents(search));

string slug = "¡Hola, Año 2026!".ToSlug();             // "hola-ano-2026"
string name = "jUAN   pérez".ToTitleCase();            // "Juan Pérez"
string avatar = user.FullName.GetInitials();          // "AC"
string preview = article.Body.RemoveHtmlTags().Truncate(120);
string phone = "5512345678".FormatPhoneNumber();      // "(551) 234 5678"
string label = user.Nickname.IfEmpty("(no name)");

bool ok = email.IsValidEmail();
bool allowed = file.Name.IsAllowedExtension(new[] { ".pdf", ".png" });
string tags = product.Tags.JoinText(", ");             // skips null / empty
```

## 2. Numbers, money and sizes

**ToMoney** uses the currency format of the current culture (right separators and symbol in es-MX, en-US, es-ES...) and can append the currency code. **ToCompact** shortens large figures for cards and charts. **PercentOf** returns 0 when the total is 0, with no division by zero. **ToFileSize** shows a file size in the right unit.

```csharp
string price = 1234.5m.ToMoney();             // "$1,234.50" (current culture)
string mxn = 1234.5m.ToMoney("MXN");          // "$1,234.50 MXN"
string visits = 3_400_000L.ToCompact();       // "3.4M" (cards and charts)

decimal tax = subtotal.ApplyPercent(16);      // 16 % of the subtotal
decimal progress = done.PercentOf(total);     // 0 when total is 0

string size = file.Size.ToFileSize();         // "1.5 MB"
long max = 5L.ToBytes(TypeStorage.Megabyte);  // 5 242 880
```

## 3. Dates

**ToRelativeTime** writes «hace 5 minutos» or «5 minutes ago» depending on the app language; a UTC date is compared with UTC time. **ToDisplay** formats dates that may be null (it returns an empty string) and can convert them to local time first. Start and end of day, week and month make range filters simple, and **EndOfDay** includes the whole last day.

```csharp
string when = comment.CreatedAt.ToRelativeTime();   // "hace 5 minutos" / "5 minutes ago"
string text = order.Date.ToDisplay();               // "24/10/2026 12:00" ("" if null)
string local = order.DateUtc.ToDisplay("g", toLocalTime: true);

// Date range filters
var from = DateTime.Today.StartOfMonth();
var to = DateTime.Today.EndOfDay();
var orders = db.Orders.Where(o => o.Date >= from && o.Date <= to);

int age = client.BirthDate.GetAge();
bool weekend = DateTime.Today.IsWeekend();
```

## 4. Queries for AstrolGrid

For the table in server mode: **SortList** sorts by the column the table asks for (also nested paths such as «Client.Name») by building an expression EF Core translates to SQL; **Paginate** takes the requested page and **ToPaginatedResponse** does all three (sort, count and page) and returns what AstrolGrid expects. **WhereIf** applies a filter only when the user filled it in. With async EF Core, combine SortList and Paginate with CountAsync and ToListAsync.

```csharp
// AstrolGrid in server mode: optional filters + sort + count + page
private async Task ReadItems(GridResponse<Client> request)
{
    var query = db.Clients
        .WhereIf(onlyActive, c => c.Active)
        .WhereIf(search.HasValue(), c => c.Name.Contains(search!));

    request.AstrolPaginatedResponse = query.ToPaginatedResponse(request.GridInfo);
}

// Async EF Core: the same steps by hand
var sorted = query.SortList(request.GridInfo.SortInfo);   // x => x.Name, nested "Client.Name"
request.AstrolPaginatedResponse = new()
{
    TotalItems = await query.CountAsync(),
    PageItems = await sorted.Paginate(request.GridInfo).ToListAsync(),
};
```

## 5. Colors

**GetColorContrast** picks the text color (white or dark, or the ones you pass) with the most contrast on a background, using the WCAG formula: handy for tags or cards with a user-chosen color. **GetContrastRatio** gives the contrast ratio (4.5 is the AA minimum for normal text) and **IsHexColor** / **NormalizeHexColor** validate and normalize what is typed in a color field.

```razor
@* Readable text on a color chosen by the user *@
<span style="background:@tag.Color; color:@tag.Color.GetColorContrast()">@tag.Name</span>

@code {
    bool valid = input.IsHexColor();                  // #rgb, #rrggbb, with or without #
    string? hex = "FA0".NormalizeHexColor();         // "#ffaa00"
    double ratio = "#facc15".GetContrastRatio("#222"); // >= 4.5: WCAG AA for text
}
```

## 6. Enums, JSON, collections and copies

**GetDisplayName** reads **[Display(Name)]** or **[Description]** from an enum value and **ToSelectList** turns the enum into options for a combo. **DeepClone** makes an independent copy (to edit in a modal and be able to cancel). **ToJson** / **FromJson** use System.Text.Json with the web options, and FromJson returns default when the text is not valid.

```csharp
public enum OrderStatus
{
    [Display(Name = "Pending payment")] Pending,
    [Description("Shipped")] Shipped,
    Delivered,
}

string text = order.Status.GetDisplayName();                         // "Pending payment"
List<SelectList<OrderStatus>> options = EnumExtensions.ToSelectList<OrderStatus>(); // for an AstrolComboBox

// Edit a copy in a modal and discard it on Cancel
var draft = client.DeepClone();

string json = filters.ToJson();                 // camelCase
var filters = json.FromJson<Filters>();         // default if empty or invalid

if (items.IsNullOrEmpty()) { /* ... */ }
foreach (var item in maybeNull.OrEmpty()) { /* ... */ }

string key = Auxiliar.NewKey(32);               // random alphanumeric key
string id = Auxiliar.NewDomId();                // "aui-k3f9x2" for label for="..."
```

### Reference

**Text** (StringExtensions)

- HasValue(), IfEmpty(fallback), Truncate(max, ellipsis)
- ToSearchKey(), ContainsIgnoreAccents(term), RemoveDiacritics(keepEnye)
- RemoveWhitespace(), CollapseWhitespace(), RemoveHtmlTags()
- ToTitleCase(culture), Capitalize(), ToSlug(maxLength), GetInitials(max)
- DigitsOnly(), FormatPhoneNumber(), IsValidEmail()
- IsAllowedExtension(extensions), JoinText(separator, skipEmpty)
- Obfuscate(key) / Deobfuscate(key): the browser storage obfuscation; it is not encryption.

**Numbers and sizes** (NumberExtensions, FileSizeExtensions)

- PercentOf(total, decimals), ApplyPercent(percent, decimals)
- ToMoney(currencyCode, culture, decimals), ToCompact(decimals, culture)
- ToFileSize(decimals), ToKilobytes(), ToMegabytes(), ToBytes(TypeStorage)

**Dates** (DateExtensions)

- ToDisplay(format, toLocalTime, culture) for DateTime, DateTimeOffset and their nullable versions
- ToRelativeTime(now, culture)
- StartOfDay(), EndOfDay(), StartOfWeek(firstDay), StartOfMonth(), EndOfMonth(), IsWeekend(), GetAge(today)

**Queries and collections** (AstrolQueryableExtensions, CollectionExtensions)

- SortList(SortInfo | json), Paginate(GridInfo), WhereIf(condition, predicate), ToPaginatedResponse(GridInfo)
- IsNullOrEmpty(), HasItems(), OrEmpty(), WhereIf for IEnumerable

**Colors, enums, JSON and copies**

- GetColorContrast(light, dark), GetContrastRatio(other), IsHexColor(), NormalizeHexColor()
- GetDisplayName(), EnumExtensions.ToSelectList<TEnum>()
- ToJson(indented), FromJson<T>()
- DeepClone()
- Auxiliar.NewKey(length), Auxiliar.NewDomId(prefix)

The style extensions (GetButtonStyle, GetBoxStyle, GetThemeColor...) are used internally by the components.


---

# Grid

> AstrolGrid is a Blazor component used to represent information, providing a grid system to display organized data using rows and columns. It allows for essential functionalities such as applying filters, sorting, pagination, and more.

Source page: https://doc.astrolui.com/basic-component/grid

## 1. Demo AstrolGrid

In this example, [confirmations](/basic-component/confirm), [notifications](/basic-component/notification), and [buttons](/basic-component/button) are implemented. It is advisable to refer to the documentation of each component for more details.

```razor
@using Astrol.Component.Basic.Grid
@using Astrol.Component.Basic.Button
@using Astrol.Component.Basic.Confirm
@using Astrol.Entities.Basic.Static.Notification
@using Astrol.Entities.Basic.UI
@using Astrol.JSInterop.Base
@inject AstrolJSInterop jsI

<AstrolConfirm @ref="_conf" />
<AstrolGrid TItem="Client" PageSize="5" Data="dataList" @ref="_grid">
   <Columns>
       <Column Name="@nameof(Client.Id)" Title="Id" Width="55px" Sortable="true" Resizable="true">
           <span>@context.Id</span>
       </Column>
       <Column Name="@nameof(Client.FullName)" Title="Full name" Width="200px" Filtrable="true" Resizable="true" />
       <Column ClassHead="blue-head" ClassRow="blue-row" Name="@nameof(Client.Points)" Title="Points" Sortable="true" Filtrable="true" Resizable="true" />
       <Column Name="@nameof(Client.MaritalStatus)" Title="Marital status" Sortable="true" Filtrable="true" Resizable="true" />
       <Column Name="@nameof(Client.Sex)" Title="Sex" Width="80px" Sortable="true" Filtrable="true" Resizable="true" />
       <Column Name="@nameof(Client.Age)" Title="Age" Filtrable="true" Resizable="true" />
       <Column Name="@nameof(Client.RegistrationDate)" Title="Date" Format="dd/MM/yyyy" TypeOf="typeof(DateOnly)" Sortable="true" Filtrable="true" Resizable="true" />
       <Column Width="60px">
           <AstrolButton Icon="astrol-trash" Title="Delete" Style="AstrolStyle.Red" OnClick="() => DeleteItem(context)" />
       </Column>
   </Columns>
</AstrolGrid>
<style>
```

```css
   /* !important: the grid header and cells use scoped css */
   .blue-head {
       background-color: rgb(from var(--color-base) r g b / 80%) !important;
   }
   .blue-row {
       background-color: rgb(from var(--color-base) r g b / 40%) !important;
   }
```

```razor
</style>
@code {
```

```csharp
   private AstrolGrid<Client>? _grid;
   private AstrolConfirm? _conf;
   private List<Client> dataList = new List<Client> {
       new Client { Id = 1, Points= 34.56F, Name = "Juan", Surnames = "Pérez", Sex = true, MaritalStatus = MaritalStatus.Widower, Age = 25, RegistrationDate = new DateTime(2022, 1, 1) },
       new Client { Id = 2, Points= 23.14F, Name = "María", Surnames = "García", Sex = false, MaritalStatus = MaritalStatus.Married, Age = 32, RegistrationDate = new DateTime(2021, 3, 15) },
       new Client { Id = 3, Points= 36.32F, Name = "Pedro", Surnames = "Rodríguez", Sex = true, Age = 45, MaritalStatus = MaritalStatus.Single, RegistrationDate = new DateTime(2020, 6, 30) },
       new Client { Id = 4, Points= 56.09F , Name = "Laura", Surnames = "Fernández", Sex = false, Age = 19, MaritalStatus = MaritalStatus.Divorced,RegistrationDate = new DateTime(2022, 2, 28) },
       new Client { Id = 5, Points= 12.05F, Name = "Carlos", Surnames = "Sánchez", Sex = true, Age = 56,MaritalStatus = MaritalStatus.Married, RegistrationDate = new DateTime(2019, 12, 1) },
       new Client { Id = 6,Points= 15.26F, Name = "Ana", Surnames = "Gómez", Age = 29, Sex = false, RegistrationDate = new DateTime(2021, 7, 10) },
       new Client { Id = 7,Points= 14.34F , Name = "Pablo", Surnames = "Martínez", Sex = true, Age = 41, MaritalStatus = MaritalStatus.Married, RegistrationDate = new DateTime(2022, 4, 5) },
       new Client { Id = 8,Points= 5.2F, Name = "Lucía", Surnames = "Jiménez", Age = 22,Sex = false, RegistrationDate = new DateTime(2023, 1, 2) },
       new Client { Id = 9,Points= 88.53F, Name = "Javier", Surnames = "Hernández",Sex = true, Age = 37,MaritalStatus = MaritalStatus.Married, RegistrationDate = new DateTime(2022, 9, 15) },
       new Client { Id = 10,Points= 45.23F , Name = "Sofía", Surnames = "Ruiz",Sex = false, Age = 28, RegistrationDate = new DateTime(2023, 3, 20) },
       new Client { Id = 11,Points= 32.54F, Name = "Miguel", Surnames = "López",Sex = true, Age = 60, MaritalStatus = MaritalStatus.Other, RegistrationDate = new DateTime(2020, 5, 11) },
       new Client { Id = 12,Points= 14.52F, Name = "Carmen", Surnames = "González",Sex = false, Age = 31, RegistrationDate = new DateTime(2021, 11, 16) },
       new Client { Id = 13,Points= 78.8F, Name = "Antonio", Surnames = "Santos",Sex = true, Age = 48, RegistrationDate = new DateTime(2020, 3, 7) },
       new Client { Id = 14,Points= 65.456F, Name = "Isabel", Surnames = "Ortega",Sex = false, Age = 20,MaritalStatus = MaritalStatus.Other, RegistrationDate = new DateTime(2022, 7, 31) },
       new Client { Id = 15,Points= 56, Name = "David", Surnames = "Ramírez",Sex = true,Age = 43, RegistrationDate = new DateTime(2019, 10, 25) },
       new Client { Id = 16,Points= 34.01F, Name = "Raquel", Surnames = "Pardo",Sex = false, Age = 26,MaritalStatus = MaritalStatus.Other, RegistrationDate = new DateTime(2021, 2, 14) },
   };
   private async Task DeleteItem(Client item) {
       if (await _conf!.Confirmation("Are you sure?", "Do you want to delete the item?")) {
           dataList.Remove(item);
           await jsI.Notification("Item removed successfully.".NotificationSuccess("astrol-ok"));
           await _grid!.RefreshGrid();
       }
   }
   public class Client {
       public int Id { get; set; }
       public string? Name { get; set; }
       public bool Sex { get; set; }
       public string? Surnames { get; set; }
       public int Age { get; set; }
       public float Points { get; set; }
       public DateTime RegistrationDate { get; set; }
       public MaritalStatus MaritalStatus { get; set; }
       public string FullName => $"{Name} {Surnames}";
   }
   public enum MaritalStatus {
       Single,
       Married,
       Divorced,
       Widower,
       Other
   }
}
```

### Supported parameters

- TItem **(object)**, type of the grid rows.
- Data **(IEnumerable<TItem>)**, in-memory data: the grid sorts, filters and pages on the client **without copying or modifying** the list. If the content changes without changing the list, call **RefreshGrid()** or change **DataVersion**.
- DataVersion **(object)**, change it to force a refresh when the content of **Data** changes without changing the reference or the number of items. It also works with **ReadItems** (calls the server again).
- ReadItems **(EventCallback<GridResponse<TItem>>)**, server-side loading (see below). When set, **Data** is not used.
- ShowLoad **(bool)**, shows the loading animation while data is being fetched (default **true**).
- IconLoad **(string)**, loading icon (default **astrol-spin5** *).
- Pageable **(bool)**, paging (default **true**).
- PageSize **(int)**, items per page (default **10**).
- PageSizeList **(List<int>)**, page size options (default **{ 5, 10, 20, 50, 100, int.MaxValue }**; **int.MaxValue** means "All").
- Selectable **(bool)**, rows selectable with a checkbox (default **false**).
- KeySelector **(Func<TItem, object?>)**, unique key of each row: keeps the selection across pages and reloads and improves performance when reordering.
- OnSelected **(EventCallback<List<TItem>>)**, raised when the selection changes, with the selected rows.
- Virtualize **(bool)**, renders only the visible rows; useful for large pages or no paging. **RowHeight** (float, approximate row height, default **41**) and **OverscanCount** (int, default **5**).
- Options **(RenderFragment)**, top area for grid buttons or options.
- Texts **(string)**: **NoSearchResultText**, **PagePaginationText**, **OfPaginationText**, **PageSizePaginationText**, **ItemPaginationText**, **AllPaginationText**, **SelectAllText**, **SelectRowText**. When not set, they follow the app language (English or Spanish). The pagination navigation button labels always come from **AstrolText**.
- Methods and properties: **RefreshGrid(resetSelection = true)** reloads the data (by default it clears the selection without raising **OnSelected**; use **RefreshGrid(false)** to keep it), **GridInfo** (current page, sort and filters) and **CurrentPageItems** (visible rows).
- Columns **(RenderFragment)**, grid columns (**<Column />**). Inside a column, **context** is the row.
  - **Name** (string): property to display, sort and filter; supports paths like **"Customer.Name"**. It is the value sent to the server in **ColumnSort** / **ColumnFilter**.
  - **Field** (Expression): typed alternative to Name, e.g. **Field="x => x.Customer.Name"**.
  - **Title** (string): header text.
  - **Format** (string): value format when there is no custom content, e.g. **"dd/MM/yyyy"** or **"N2"**.
  - **Width** (string): column width (default **auto**).
  - **Sortable** (bool): sorting when clicking the header (ascending, descending, none); requires **Name** or **Field** (default **false**).
  - **Filtrable** (bool): header filter based on the property type: text, number, date (DateOnly), date and time (DateTime), time (TimeOnly / TimeSpan), bool or enum; other types show no filter (default **false**).
  - **FilterPlaceholder** (string): filter placeholder.
  - **TypeOf** (Type): type used to choose the filter when it cannot be inferred, e.g. **typeof(DateOnly)**.
  - **DefaultValue** (object): initial filter value.
  - **Resizable** (bool): width can be changed by dragging the right edge; it is kept when paging or sorting (default **false**).
  - **Id** (string): column identifier (optional).
  - **ClassHead** / **ClassRow** (string): css classes for the header and the cells.
  - **ChildContent** (RenderFragment<TItem>): custom cell content; the row is **context**.
- ReadItems **(EventCallback<GridResponse<TItem>>)**, loading from your API. It receives **GridInfo** and must fill **AstrolPaginatedResponse**:
  - **GridInfo**: **Page** (int), **PageSize** (int), **SortInfo** (**ColumnSort**, **SortDirection**: None / Ascending / Descending) and **FilterInfo** (list of **ColumnFilter** / **ValueFilter**).
  - **AstrolPaginatedResponse<TItem>**: **TotalItems** (int) and **PageItems** (IEnumerable<TItem>).
  - On the server you can use **query.SortList(gridInfo.SortInfo).Paginate(gridInfo)**: it builds expressions that EF Core translates to SQL.
  - Filters are not applied automatically on the server: loop through **FilterInfo** and apply them to your query (**ValueFilter** arrives as text). Computed properties (e.g. **FullName**) sort in memory but EF Core cannot translate them to SQL.

## 2. Demo AstrolGrid selectable with options

This example simulates loading data from the server; rows are selectable and column filtering has been disabled.

**KeySelector** is needed to keep the selection across pages when data comes from the server (each read returns new objects). After changing the data call **RefreshGrid()** through **@ref** (it clears the selection; **RefreshGrid(false)** keeps it). **DataVersion** is optional: change it to force a refresh from parameters.

```razor
@using Astrol.Component.Basic.Grid
@using Astrol.Component.Basic.Button
@using Astrol.Entities.Basic.UI
@using Astrol.Entities.Basic.UI.Grid
@using Astrol.Entities.Basic.Response
@using Astrol.Entities.Basic.Static.Extensions

<AstrolGrid TItem="Client" PageSize="5" ReadItems="ReadItems" Selectable="true"
            KeySelector="x => x.Id" OnSelected="OnSelected" @ref="_gridServer">
   <Options>
       <AstrolButton Icon="astrol-trash" Style="AstrolStyle.Red" Text="Delete"
                     OnClick="DeleteSelected" Status="@(_selected.Count > 0)" />
   </Options>
   <Columns>
       <Column Name="@nameof(Client.Id)" Title="Id" Width="55px" Sortable="true" />
       <Column Name="@nameof(Client.FullName)" Title="Full name" Sortable="true" />
       <Column Name="@nameof(Client.Points)" Title="Points" Sortable="true" />
       <Column Name="@nameof(Client.MaritalStatus)" Title="Marital status" Sortable="true" />
       <Column Name="@nameof(Client.Sex)" Title="Sex" Width="80px" Sortable="true" />
       <Column Name="@nameof(Client.Age)" Title="Age" />
       <Column Name="@nameof(Client.RegistrationDate)" Title="Date" Format="dd/MM/yyyy" Sortable="true" />
   </Columns>
</AstrolGrid>
@code {
```

```csharp
   private AstrolGrid<Client>? _gridServer;
   private List<Client> _selected = new();
   // Simulates the database table (on a real server: an EF Core IQueryable).
   private List<Client> _db = new List<Client> { /* same data as example 1 */ };

   private async Task ReadItems(GridResponse<Client> request) {
       await Task.Delay(200); // simulated latency
       // Sorts, counts and pages (Astrol.Entities.Basic.Static.Extensions)
       request.AstrolPaginatedResponse = _db.AsQueryable().ToPaginatedResponse(request.GridInfo);

       // Async EF Core: same steps with SortList + Paginate
       // var query = dbContext.Clients.SortList(request.GridInfo.SortInfo);
       // request.AstrolPaginatedResponse = new() {
       //     TotalItems = await query.CountAsync(),
       //     PageItems = await query.Paginate(request.GridInfo).ToListAsync() };
   }
   private void OnSelected(List<Client> selected) => _selected = selected;
   private async Task DeleteSelected() {
       var ids = _selected.Select(x => x.Id).ToHashSet();
       _db.RemoveAll(x => ids.Contains(x.Id));
       _selected = new();
       await _gridServer!.RefreshGrid(); // reads again and clears the selection
   }
}
```


---

# Icon

> AstrolIcon is a Blazor component that visually represents an icon. It is used to convey visual information to the user, such as actions, objects, or ideas in general.

Source page: https://doc.astrolui.com/basic-component/icon

## 1. Demo AstrolIcon

```razor
@using Astrol.Component.Basic.Icon
<!-- Razor component -->
<AstrolIcon Icon="astrol-emo-wink" />
<AstrolIcon Icon="astrol-spin2" Animation="true" />
<!-- HTML component -->
<i class="astrol-star-filled"></i>
<i class="astrol-heart-filled"></i>
<i class="astrol-certificate"></i>
```

### Supported parameters

- **Icon** (string): icon class, for example **astrol-home** (**required**).
- **Class** (string?): additional CSS class (not required).
- **Animation** (bool): if **true** the icon spins (adds the **animate-spin** class) (default is **false**).


---

# JS utilities

> Astrol.JSInterop.Base for Blazor: typed localStorage and sessionStorage (with obfuscated values), copy to clipboard, file downloads, time zone, language, media queries and logout on inactivity.

Source page: https://doc.astrolui.com/basic-component/js-interop

Astrol.JSInterop.Base: browser storage, clipboard, files and browser data from C#.

**Astrol.JSInterop.Base** comes with Astrol.Component.Basic and gathers the browser calls almost every app needs, so you don't write JavaScript. Its JS module is downloaded the first time it is used. **AddAstrolBasic()** already registers **AstrolJSInterop**; storage is a set of extension methods of **IJSRuntime**.

```razor
@* Program.cs: builder.Services.AddAstrolBasic(); (registers AstrolJSInterop) *@
@using Astrol.JSInterop.Base
@inject AstrolJSInterop jsI   @* clipboard, files, browser, idle timer *@
@inject IJSRuntime js         @* storage: extension methods of IJSRuntime *@
```

## 1. localStorage and sessionStorage

Store preferences, filters, a wizard's last step or a draft with its C# type: the value becomes JSON when saved and goes back to its type when read; if it doesn't exist you get **default**. **localStorage** survives closing the browser and **sessionStorage** lasts only as long as the tab.

By default (**useEncrypt = true**) the value is stored **obfuscated**: it can't be read at a glance in the browser tools, which adds a layer of discretion. It is not security-grade encryption: don't store passwords, tokens or sensitive data in the browser. With **useEncrypt: false** readable JSON is stored (e.g. to share it with JavaScript code). Always read with the same **useEncrypt** value you saved with.

Try it: save with and without **useEncrypt** and compare the stored value.

```csharp
public record Preferences(string Theme, int PageSize);

// Save any serializable value (stored as JSON; obfuscated by default)
await js.SetInLocalStorage("prefs", new Preferences("dark", 20));

// Read it back with its type (default if it does not exist)
var prefs = await js.GetFromLocalStorage<Preferences>("prefs");

bool exists = await js.ExistsInLocalStorage("prefs");
await js.RemoveFromLocalStorage("prefs");
await js.ClearLocalStorage();

// Same API for sessionStorage (cleared when the tab is closed)
await js.SetInSessionStorage("wizard-step", 3);
int step = await js.GetFromSessionStorage<int>("wizard-step");

// Plain, readable JSON (e.g. to share it with JavaScript code)
await js.SetInLocalStorage("theme", "dark", useEncrypt: false);
```

## 2. Clipboard and files

**CopyToClipboard** copies a text (returns **false** if the browser doesn't allow it). **SaveAs** downloads a file generated in the app from its bytes (a CSV, a PDF, an Excel...) and **DownloadFile** one that is already at a URL, with the name you choose.

```csharp
bool copied = await jsI.CopyToClipboard("dotnet add package Astrol.Component.Basic");

// A file generated in the app (CSV, PDF, Excel... as byte[])
await jsI.SaveAs("clients.csv", Encoding.UTF8.GetBytes(csv));

// A file that is already at a URL
await jsI.DownloadFile("files/report.pdf", "report-2026.pdf");
```

## 3. Browser data and actions

The user's time zone and language (for dates and texts), **MatchesMedia** for any CSS media query (mobile, dark mode, print...), opening a new tab safely and scrolling to an element or to the top of the page (also inside the AstrolLayoutMenu body).

```csharp
string timeZone = await jsI.GetTimeZone();           // "America/Tijuana"
string language = await jsI.GetBrowserLanguage();    // "es-MX"
bool isMobile = await jsI.MatchesMedia("(max-width: 768px)");
bool prefersDark = await jsI.MatchesMedia("(prefers-color-scheme: dark)");

await jsI.OpenInNewTab("https://astrolui.com");
await jsI.ScrollToElement("#results");
await jsI.ScrollToTop();
```

## 4. Logout on inactivity

**IdleTimer** calls your **[JSInvokable] Logout()** method when the user hasn't moved the mouse, typed, scrolled or touched the screen for a while. The last activity is shared between tabs: working in one keeps the session alive in the others.

```csharp
// MainLayout.razor.cs: log out after 30 minutes without activity
private DotNetObjectReference<MainLayout>? self;

protected override async Task OnAfterRenderAsync(bool firstRender)
{
    if (firstRender)
    {
        self = DotNetObjectReference.Create(this);
        await jsI.IdleTimer(self, storageKey: "myapp", time: 30 * 60 * 1000);
    }
}

[JSInvokable]
public async Task Logout()
{
    await AuthService.LogoutAsync();
    Navigation.NavigateTo("/login");
}
```

### Reference

**Storage** (IJSRuntime extensions, **useEncrypt** defaults to **true**)

- SetInLocalStorage<T>(key, value, useEncrypt) / SetInSessionStorage<T>(...)
- GetFromLocalStorage<T>(key, useEncrypt) / GetFromSessionStorage<T>(...): the value or **default**.
- ExistsInLocalStorage(key) / ExistsInSessionStorage(key)
- RemoveFromLocalStorage(key) / RemoveFromSessionStorage(key)
- ClearLocalStorage() / ClearSessionStorage(): remove every key of the site.

**AstrolJSInterop**

- CopyToClipboard(text) → **bool**
- SaveAs(fileName, bytes) and DownloadFile(url, fileName)
- GetTimeZone() and GetBrowserLanguage() → **string**; MatchesMedia(query) → **bool**
- OpenInNewTab(url), ScrollToElement(selector, smooth) and ScrollToTop(smooth)
- IdleTimer(dotNetRef, storageKey, time): calls **Logout()** after **time** ms without activity (default 30 minutes).
- Notification(notification): classic notifications; in new code use **IAstrolToast** (see Notification).
- DOM helpers used by the components: FocusElement, GetWidthBySelector, GetHeightBySelector, CountElementExistToHTML, SetInputValue, Prompt.


---

# LayoutMenu

> AstrolLayoutMenu is a Blazor component designed to completely replace the content of MainLayout.

Source page: https://doc.astrolui.com/basic-component/layout-menu

## Video tutorial

## 1. Demo AstrolLayoutMenu

```razor
@inherits LayoutComponentBase
@using Astrol.Component.Basic.Layout
@using Astrol.Entities.Basic.UI
<AstrolLayoutMenu Style="AstrolTheme.Yellow"
                  Mode="@mode"
                  ShowSetMode="true"
                  OnChangeThemeMode="m => mode = m"
                  StatusToggleMenu="@menuOpen"
                  OnChangeToggleMenu="open => menuOpen = open">
   <Top>
       <b>Options</b>
   </Top>
   <Menu>
       <b>Menu</b>
   </Menu>
   <Body>
       <div style="padding:20px;">
           @Body
       </div>
   </Body>
</AstrolLayoutMenu>
@code {
    // Light, Dark or Auto (follows the operating system)
    private AstrolThemeMode mode = AstrolThemeMode.Auto;
    private bool menuOpen = true;
}
```

### Supported parameters

- Top, Menu, Body **(RenderFragment)**, content of the top bar, side menu and body.
- Style **(AstrolTheme)**, theme color (default **Yellow**): Yellow, Orange, Green, Blue, Red, Purple.
- Mode **(AstrolThemeMode?)**, color mode:
  - **Light**: light.
  - **Dark**: dark.
  - **Auto**: follows the operating system preference and changes live if the user changes it.

When not set, **Outline** is used.

- Outline **(bool)**, classic mode: **true** light, **false** dark (default **true**). Ignored when **Mode** is set.
- ShowSetMode **(bool)**, shows the button to change the mode (default **false**). The button only reports the change: update **Mode** (or **Outline**) in the event.
- OnChangeThemeMode **(EventCallback<AstrolThemeMode>)**, when set, the button cycles **light → dark → automatic**. Store the value if you want to keep it after a reload.
- OnChangeMode **(EventCallback<bool>)**, classic two-state alternative (true = light); not raised when switching to automatic.
- ApplyThemeToDocument **(bool)**, also applies the theme to **<html>** so notifications and everything outside the layout use it (default **true**).
- IncludeServiceHosts **(bool)**, includes the **IAstrolToast** and **IAstrolModal** hosts (default **true**).
- StatusToggleMenu **(bool)**, side menu expanded (default **true**), and OnChangeToggleMenu **(EventCallback<bool>)**, receives the new state when the button is pressed; the component does not change the value by itself, update it in this event.
- WidthMenu **(int)**, menu width in px (default **280**); HeightTop **(int)**, top bar height in px (default **50**).
- Class **(string)**, custom css class.
- It passes the cascading values **ThemeStyle** (AstrolTheme) and **OutlineMode** (bool, true = light) to its children.
- **SetOutline**, the mode button, can also be used on its own: Mode **(AstrolThemeMode)**, AllowAuto **(bool)**, includes automatic mode in the cycle (default **false**), and OnChange **(EventCallback<AstrolThemeMode>)**, receives the next mode.


---

# Load

> AstrolLoad and PartialLoad are Blazor components that display a loading animation, over the whole page or over a parent container, to show the user that a response is pending after an action.

Source page: https://doc.astrolui.com/basic-component/load

## 1. Demo PartialLoad

This component displays an animation over its parent container to show the user that a response is pending after an action. The parent container must have **position: relative** (or any position other than static), because the overlay fills 100% of its width and height.

```razor
@using Astrol.Component.Basic.Load
<div style="height:150px;width:150px;overflow:hidden;position:relative;border:1px solid var(--color-dark);">
   <PartialLoad WidthAndHeightLoad="150" Status="statusPartialLoad" Icon="astrol-spin4" />
</div>
@code {
```

```csharp
   private bool statusPartialLoad = true;
}
```

### Supported parameters

- **Status** (bool): whether the animation is displayed (default is **false**).
- **WidthAndHeightLoad** (int): width and height in pixels of the box that holds the icon (default is **100** in **PartialLoad** and **150** in **AstrolLoad**).
- **Icon** (string): icon to display, always animated (default is **astrol-spin5**).
  - **astrol-spinner** *
  - **astrol-spin1** *
  - **astrol-spin2** *
  - **astrol-spin3** *
  - **astrol-spin4** *
  - **astrol-spin5** *
  - **astrol-spin6** *

These parameters are the same for **PartialLoad** and **AstrolLoad**.

## 2. Demo AstrolLoad

This component displays an animation over the whole page to show the user that a response is pending after an action. While **Status** is **true**, the overlay blocks interaction with the page.

```razor
@using Astrol.Component.Basic.Load
<AstrolLoad Status="statusLoad" />
<AstrolButton Text="Open Load" Style="AstrolStyle.Blue" OnClick="OpenLoad" />
@code {
```

```csharp
   private bool statusLoad = false;
   private async Task OpenLoad() {
       statusLoad = true;
       await Task.Delay(1000); // your work here
       statusLoad = false;
   }
}
```


---

# MenuAdmin

> AstrolMenuAdmin is a Blazor component intended to be used within the template, but it can also be encapsulated within any component. It's important to note that it takes up 100% of the width within its parent component.

Source page: https://doc.astrolui.com/basic-component/menu-admin

## Video tutorial

## 1. Demo AstrolMenuAdmin

The component is intended to be used within the [template (AstrolLayoutMenu)](/basic-component/layout-menu), but it can also be encapsulated within any component. It's important to note that it takes up 100% of the width within its parent component.

```razor
@using Astrol.Entities.Basic.UI
@using Astrol.Component.Basic.Menu
<div style="float:left;width:300px;background:var(--background-menu);position:relative;max-height:400px;">
   <AstrolMenuAdmin MenuList="optionsMenu" />
</div>
@code {
```

```csharp
   List<MenuItem> optionsMenu = new List<MenuItem> {
       new MenuItem {
           URL = "/",
           Icon = "astrol-home",
           Name = "Home",
       },
       new MenuItem {
           Icon = "astrol-th-outline",
           Name = "Web sites",
           StatusSubMenu = true,
           SubMenus = new List<MenuItem> {
               new MenuItem {
                   URL = "https://astrolui.com",
                   Icon = "astrol-heart-filled",
                   Name = "AstrolUi",
               },
               new MenuItem {
                   URL = "https://perender.com",
                   Icon = "astrol-star-filled",
                   Name = "PERENDER",
                   IsNew = true
               },
           }
       }
   };
}
```

### Supported parameters

- MenuList **(List<MenuItem>)**, menu items (one submenu level is supported).
- SelectByUrl **(bool)**, selects the item whose **URL** matches the current page (or the longest prefix: **/clients/5** selects **/clients**) and opens its submenu; also when navigating with links or the browser buttons (default **true**).
- **MenuItem** properties (**@using Astrol.Entities.Basic.UI**):
  - **Name** (string), item text, rendered as **plain text**. It may repeat (e.g. several «Installation»): the active item is identified by its URL.
  - **NameIsHtml** (bool), renders **Name** as HTML (default **false**); use it only with trusted content.
  - **Icon** (string), icon css class (optional).
  - **URL** (string), navigation address. With a URL the item is a link; without one it is a button that only expands its submenu.
  - **Active** (bool), selected item (default **false**); with **SelectByUrl** it is computed from the URL.
  - **Section** (string), group title (e.g. «General», «Packages»): the item that sets it starts a new group and the following ones without **Section** belong to it.
  - **IsNew** (bool), highlights the option with a **new** label (default **false**).
  - **StatusSubMenu** (bool), submenu expanded (default **false**).
  - **SubMenus** (List<MenuItem>), submenu items.
  - **Roles** (string), comma-separated roles for which a **submenu** item is shown (uses **AuthorizeView**, authentication must be configured). The parent item is shown if the user has any of its children's roles; if any child has no roles, the parent is always shown. **Roles** on a top-level item are ignored.


---

# Modal

> AstrolModal is a Blazor component used to generate a popup window on the page to display additional content, allowing advanced interaction with the user.

Source page: https://doc.astrolui.com/basic-component/modal

## 1. Demo AstrolModal

In this example, [buttons](/basic-component/button) are implemented, so it is recommended to refer to their documentation for more information.

```razor
@using Astrol.Entities.Basic.UI
@using Astrol.Component.Basic.Button
@using Astrol.Component.Basic.Modal

<AstrolModal Title="Demo" Status="_statusModal" OnChangeStatus="StatusModal">
   <!-- Content -->
   <h1>Hello World!</h1>
</AstrolModal>
<AstrolButton Text="Open" Style="AstrolStyle.Blue" OnClick="() => StatusModal(true)" />
@code {
```

```csharp
   private bool _statusModal = false;
   private void StatusModal(bool newStatus) {
       _statusModal = newStatus;
   }
}
```

### Supported parameters

- Status **(bool)**, modal visibility. **@bind-Status** is not supported: update your variable in **OnChangeStatus**.
- OnChangeStatus **(EventCallback<bool>)**, raised with **false** when the modal closes itself (Close button, X, click outside or **Esc**).
- Title **(string)**, modal title (also its accessible name).
- ChildContent **(RenderFragment)**, modal content.
- Class **(string)**, custom css class.
- Draggable **(bool)**, can be moved by dragging the header (default **true**).
- Resizable **(bool)**, can be resized from the edges (default **true**).
- ClosedInteractive **(bool)**, closes when clicking outside the content or pressing **Esc** (default **true**).
- Outline **(bool)** and OutlineButton **(bool)**, outline style for the modal and the close button (default **false**).
- ShowHead **(bool)**, shows the header with title and buttons (default **true**).
- ShowOptions **(bool)**, shows the bottom bar, where **ButtonOption (RenderFragment)** and the close button are rendered (default **true**).
- ShowButtonClose **(bool)**, Close button visibility (default **true**).
- TextClose, TextMaximize, TextRestore **(string)**, button texts (default follows the app language).
- Width **(AstrolWidth)**, initial max width (default **Middle**), and WidthMaximize **(AstrolWidth?)**, width when maximized; the maximize button only appears when it is set and differs from Width:
  - **AstrolWidth.Mini** 300px
  - **AstrolWidth.Short** 450px
  - **AstrolWidth.Middle** 768px
  - **AstrolWidth.Large** 1200px
  - **AstrolWidth.Full** 100% of the browser
- OnChangeWidth **(EventCallback<AstrolWidth>)**, raised with the new width when maximizing or restoring.
- The modal is a native **<dialog>**: it is always on top, the background page cannot be used while it is open, **Esc** closes only the top modal and focus returns to the button that opened it.
- From code, without **Status** or **@ref**: **await Modal.ShowAsync<MyComponent>("Title", parameters, options)** or **await Modal.ShowAsync(fragment, "Title", options)** with **@inject IAstrolModal Modal**. The component closes itself with **[CascadingParameter] AstrolModalReference** and **Close(result)** or **Cancel()**. It returns a **ModalResult** (**Cancelled**, **Data**, **GetData<T>()**).
- **ModalOptions**: Width (Middle), WidthMaximize, Draggable (true), Resizable (false), ClosedInteractive (true), ShowHead (true), ShowOptions (true), Outline (modal and button), Class and TextClose.


---

# Notification

> The Notification component in Blazor allows you to inform users about relevant events. These visual alerts appear temporarily on the screen and can contain information about events, interactions, or important reminders.

Source page: https://doc.astrolui.com/basic-component/notification

## 1. Minimum notifications

In this example, [buttons](/basic-component/button) are implemented, so it is recommended to refer to their documentation.

```razor
@using Astrol.Entities.Basic.Static.Notification
@using Astrol.Component.Basic.Button
@using Astrol.Entities.Basic.UI
@using Astrol.JSInterop.Base
@inject AstrolJSInterop jsI

<AstrolButton OnClick="x=>ShowMinimalNotification()"
              Style="AstrolStyle.Blue"
              Text="Click me" />
@code {
```

```csharp
   private async Task ShowMinimalNotification() {
       await Task.Delay(400);
       await jsI.Notification("Minimum notification: Base".NotificationBase());
       await Task.Delay(400);
       await jsI.Notification("Minimum notification: None".NotificationNone());
       await Task.Delay(400);
       await jsI.Notification("Minimum notification: Info".NotificationInfo());
       await Task.Delay(400);
       await jsI.Notification("Minimum notification: Error".NotificationError());
       await Task.Delay(400);
       await jsI.Notification("Minimum notification: Warning".NotificationWarning());
       await Task.Delay(400);
       await jsI.Notification("Minimum notification: Success".NotificationSuccess());
   }
}
```

Open all minimum notifications

## 2. Custom notifications

```razor
@using Astrol.Component.Basic.Button
@using Astrol.Entities.Basic.UI
@using Astrol.JSInterop.Base
@inject AstrolJSInterop jsI

<AstrolButton OnClick='x => ShowNotification("Hello World!", "astrol-ok", AstrolStyle.Blue)'
              Style='AstrolStyle.Blue'
              Text='Click me' />
@code {
```

```csharp
   private async Task ShowNotification(string message,string icon, AstrolStyle type, bool outline = false) {
       await jsI.Notification(new Notification
       {
           Type = type,
           Icon = icon,
           Message = message,
           Outline = outline,
       });
   }
}
```

## 3. IAstrolToast / IAstrolModal

Recommended way: the **IAstrolToast** and **IAstrolModal** services are injected into any component, need no **@ref** and are rendered by Blazor.

```csharp
// Program.cs
using Astrol.Component.Basic;
builder.Services.AddAstrolBasic();
```

```razor
@using Astrol.Component.Basic.Toast
@using Astrol.Component.Basic.Modal
@inject IAstrolToast Toast
@inject IAstrolModal Modal
@* AstrolLayoutMenu already includes <AstrolToastHost /> and <AstrolModalHost /> *@
@code {
```

```csharp
   private void Save() {
       Toast.Success("Saved");
       Toast.Error("Could not save\nPlease try again");
   }
   private async Task Delete() {
       if (await Modal.ConfirmAsync("Are you sure?", "The item will be deleted."))
           Toast.Success("Deleted");
   }
   private async Task Edit() {
       // EditUser: your component; it closes itself with [CascadingParameter] AstrolModalReference
       var result = await Modal.ShowAsync<EditUser>("Edit", new Dictionary<string, object?> { ["Id"] = 5 });
       if (!result.Cancelled) { var user = result.GetData<User>(); }
   }
}
```

### Supported parameters

**IAstrolToast service (recommended)**: **@inject IAstrolToast Toast** and **Toast.Success / Error / Warning / Info("message", seconds)** (default 5 / 8 / 6 / 5 seconds), **Toast.Show("message", style, icon, seconds, outline)**, **Toast.Show(notification)** with the model below, or **Toast.Clear()**. It is rendered by Blazor, pauses on hover, can be closed with the keyboard, follows the theme and stays above modals. Requires **AddAstrolBasic()**; **AstrolLayoutMenu** already includes the host (without it, add **<AstrolToastHost />** once, e.g. in MainLayout; with no host the JS notification is used).

String extensions (**@using Astrol.Entities.Basic.Static.Notification**), for **jsI.Notification(...)** or **Toast.Show(...)**: **"text".NotificationSuccess()**, **NotificationError**, **NotificationWarning**, **NotificationInfo**, **NotificationNone** and **NotificationBase**, with optional parameters **(icon = "astrol-warning", outline = true, time = 5, allowHtml = false)**.

**Notification** model (also for **jsI.Notification(...)**):

- Message **(string)**, text to display. Line breaks **\n** are kept.
- AllowHtml **(bool)**, renders the message as HTML. **Default false** (plain text, prevents HTML injection); use it only with trusted content.
- Icon **(string)**, icon (default **astrol-warning ***).
- ShowLoad **(bool)**, lifetime bar (default **true**).
- Outline **(bool)**, style without fill (default **false**; **true** in the extensions).
- Time **(int)**, seconds visible (default **5**); with IAstrolToast, **0** = stays until closed (with jsI.Notification it closes immediately).
- Type **(AstrolStyle)**, color: Base, White, Black, Red, Orange, Green, Blue, Yellow, Purple.


---

# Pagination

> AstrolPagination: Blazor pagination with page, page size and total items.

Source page: https://doc.astrolui.com/basic-component/pagination

Page navigation for grids or server-side paged lists.

## 1. Demo AstrolPagination

```razor
@using Astrol.Component.Basic.Pagination
@using Astrol.Entities.Basic.UI.Grid

<AstrolPagination Page="@page" PageSize="@pageSize" ItemCount="@total" PaginationChange="OnChange" />

@code {
    private int page = 1;
    private int pageSize = 10;
    private int total = 237;

    private async Task OnChange(GridInfo info)
    {
        page = info.Page;
        pageSize = info.PageSize;
        // load the page from the server with info.Page / info.PageSize
    }
}
```

### Supported parameters

- **Page** (int): current page (default **1**).
- **PageSize** (int): items per page (default **10**).
- **PageSizeList** (List<int>): sizes offered by the selector (default **5, 10, 20, 50, 100**).
- **ItemCount** (int): total items (used to compute the number of pages).
- **PaginationChange** (EventCallback<GridInfo>): when the page or size changes or refresh is pressed; **GridInfo** has **Page** and **PageSize**.
- **TextPage, TextOf, TextPageSize, TextItem, TextAll** (string?): texts (default in the app language).

AstrolGrid already includes it; use it alone for server-side paged lists or cards.


---

# Tabs

> AstrolTabs: Blazor tabs with icons, badges, disabled tabs, keyboard (arrows, Home, End), @bind-ActiveTabIndex and panels that keep their state.

Source page: https://doc.astrolui.com/basic-component/tabs

Accessible tabs, underlined or as buttons.

## 1. Demo AstrolTabs

Each **AstrolContentTab** is a tab: its **Title** (with optional **Icon** and **Badge**) goes in the list and its content in the panel. With focus on the list, the arrows, **Home** and **End** change tab and skip disabled ones.

```razor
@using Astrol.Component.Basic.Tabs

<AstrolTabs @bind-ActiveTabIndex="active" AriaLabel="Customer">
    <AstrolContentTab Title="General" Icon="astrol-user">
        <p>Name, email and phone...</p>
    </AstrolContentTab>
    <AstrolContentTab Title="Orders" Icon="astrol-basket" Badge="3">
        <p>The last orders...</p>
    </AstrolContentTab>
    <AstrolContentTab Title="Billing" Icon="astrol-credit-card" Disabled="true">
        ...
    </AstrolContentTab>
</AstrolTabs>

@code {
    private int active;
}
```

The customer's name, email and phone.

The customer's last orders.

## 2. Buttons and panels that keep their state

**Pills** shows the tabs as buttons. By default only the active panel exists; with **KeepAlive** the others stay hidden in the page and keep what was typed: type something, switch tab and come back.

```razor
@* Pills: buttons instead of underline. KeepAlive: hidden tabs keep what was typed *@
<AstrolTabs Pills="true" KeepAlive="true">
    <AstrolContentTab Title="Notes">
        <AstrolContentInput><textarea></textarea></AstrolContentInput>
    </AstrolContentTab>
    <AstrolContentTab Title="Preview">...</AstrolContentTab>
</AstrolTabs>
```

Type something and switch tab

Go back to «Notes»: the text is still there.

### Supported parameters

**AstrolTabs**

- ActiveTabIndex **(int)**, active tab from 0; binds with **@bind-ActiveTabIndex** (default **0**).
- Pills **(bool)**, tabs as rounded buttons (default **false**, underlined).
- KeepAlive **(bool)**, keeps inactive panels hidden so they keep their state (default **false**).
- AriaLabel **(string)**, accessible text of the tab list.
- Class **(string)**, extra css class.
- SelectAsync(int) **(method)**, activates a tab from code.

**AstrolContentTab**

- Title **(string)**, tab text.
- Icon **(string)**, **astrol-*** icon (optional).
- Badge **(string)**, short text next to the title, e.g. a counter (optional).
- Disabled **(bool)**, disabled tab (default **false**).
- ChildContent **(RenderFragment)**, panel content.

Tabs follow the order in which they are created; one that appears later (inside an **@if**) is added at the end.


---

# ThemeSwitcher

> AstrolThemeSwitcher: theme color and light, dark or automatic mode selector for Blazor.

Source page: https://doc.astrolui.com/basic-component/theme-switcher

Theme color and light/dark mode, to place wherever you want (for example in the top bar).

## 1. Demo AstrolThemeSwitcher

The demo changes only affect the demo. The same component controls the docs in the top right corner.

```razor
@using Astrol.Component.Basic.Layout

<AstrolThemeSwitcher @bind-Theme="theme" @bind-Mode="mode" />
<AstrolThemeSwitcher ShowMode="false" @bind-Theme="theme" />
<AstrolThemeSwitcher ShowColors="false" AllowAuto="false" @bind-Mode="mode" />
```

## 2. Custom color and tooltips

With **AllowCustomColor** one more circle with a color picker appears: the user picks any color and the theme becomes **AstrolTheme.Custom** with **CustomColor** (both support **@bind**). **Colors** limits which predefined colors are offered. Color names and the mode button action are shown with **AstrolTooltip**; with **ShowTooltips="false"** no help is shown (the aria-label is kept for screen readers).

In the demo the theme only applies to its container: pick a color and watch the button and the toggle change. For the whole app, see [Theme](/theme).

```razor
@* Any color: the theme becomes AstrolTheme.Custom with CustomColor *@
<AstrolThemeSwitcher @bind-Theme="theme" @bind-CustomColor="customColor" AllowCustomColor="true" />

@* Only some colors and without tooltips *@
<AstrolThemeSwitcher @bind-Theme="theme" ShowTooltips="false"
                     Colors="new[] { AstrolTheme.Yellow, AstrolTheme.Blue }" />

@* The layout (and <html>) applies the custom color *@
<AstrolLayoutMenu Style="@theme" CustomColor="@customColor" Mode="@mode"> ... </AstrolLayoutMenu>
```

## 3. In the layout top bar

Put it in the **Top** of **AstrolLayoutMenu** (next to the user, notifications...) and turn off the side menu mode button with **ShowSetMode="false"**. The layout repaints with the new color without reloading; saving the preference is up to your app.

```razor
<AstrolLayoutMenu Style="@theme" Mode="@mode" ShowSetMode="false" OnChangeThemeMode="SaveMode">
    <Top>
        <a class="my-logo" href="/"><img src="img/logo.svg" alt="MyApp" /></a>
        <div class="my-top-actions">
            <AstrolThemeSwitcher Theme="@theme" ThemeChanged="SaveTheme" Mode="@mode" ModeChanged="SaveMode" />
            @* user menu, notifications... *@
        </div>
    </Top>
    <Menu> <AstrolMenuAdmin MenuList="menu" /> </Menu>
    <Body> @Body </Body>
</AstrolLayoutMenu>
```

```csharp
private async Task SaveTheme(AstrolTheme value)
{
    theme = value;          // the layout repaints with the new color, no reload needed
    await js.InvokeVoidAsync("localStorage.setItem", "theme", value.ToString());
}
```

### Supported parameters

- Theme **(AstrolTheme)** and ThemeChanged, theme color (supports **@bind-Theme**).
- Mode **(AstrolThemeMode)** and ModeChanged, **Light**, **Dark** or **Auto** mode (supports **@bind-Mode**).
- AllowAuto **(bool)**, the mode button includes automatic, which follows the system (default **true**).
- ShowColors, ShowMode **(bool)**, show the colors and the mode button (default **true**).
- ShowTooltips **(bool)**, color names and mode action in an AstrolTooltip; with **false**, no visible help (default **true**).
- Colors **(IEnumerable<AstrolTheme>?)**, predefined colors offered (default all).
- AllowCustomColor **(bool)**, adds the custom color picker (default **false**).
- CustomColor **(string?)** and CustomColorChanged, custom color in hexadecimal (supports **@bind-CustomColor**).
- Class **(string?)**, additional css class.


---

# Title

> AstrolTitle is a Blazor component that allows setting the title of the current page at the interface level within the body and at the browser level. It also allows setting elements for the header and metadata of the current page.

Source page: https://doc.astrolui.com/basic-component/title

## 1. Demo AstrolTitle

```razor
@using Astrol.Component.Basic.Title
<AstrolTitle Icon="astrol-star-1" Text="Example" SetTextAsPageTitle="false" />

<!-- Page title + metadata (requires <HeadOutlet />) -->
<AstrolTitle Icon="astrol-star-1" Text="Example">
   <HeadContent>
       <meta name="description" content="Example...">
       <meta property="og:url" content="https://doc.astrolui.com" />
   </HeadContent>
</AstrolTitle>
```

### Supported parameters

- **Text** (string?): title text (not required).
- **Icon** (string?): class of the icon before the text, in a square tinted with the theme color (not required).
- **Description** (string?): secondary text under the title (not required).
- **Class** (string?): additional CSS class added to **astrol-cont-title** (not required).
- **SetTextAsPageTitle** (bool): if **true** and **Text** is not empty, the text is also used as the browser tab title through **PageTitle** (default is **true**).
- **HeadContent** (RenderFragment?): content added to the page <head>, such as metadata (**not required**).

**PageTitle** and **HeadContent** require the app to include the **<HeadOutlet />** component.


---

# Tooltip

> AstrolTooltip: Blazor help text that appears on hover or keyboard focus, in four positions, accessible (aria-describedby) and never clipped by grids or modals.

Source page: https://doc.astrolui.com/basic-component/tooltip

Help text on hover or focus.

## 1. Demo AstrolTooltip

Wrap the element with **AstrolTooltip**. It appears on hover (after **Delay** ms) or right away on keyboard focus, and closes with Esc. If it doesn't fit on the chosen side, it goes to the opposite one. The focusable element gets **aria-describedby**, so screen readers read the help.

```razor
@using Astrol.Component.Basic.Tooltip

<AstrolTooltip Text="Save the changes">
    <AstrolButton Text="Top" Style="AstrolStyle.White" />
</AstrolTooltip>
<AstrolTooltip Text="Opens below" Placement="AstrolTooltipPlacement.Bottom">
    <AstrolButton Text="Bottom" Style="AstrolStyle.White" />
</AstrolTooltip>

@* Own content: Content instead of Text. An icon needs tabindex="0" to be reachable by keyboard *@
<AstrolTooltip Placement="AstrolTooltipPlacement.Bottom">
    <ChildContent>
        <i class="astrol-help-circled" tabindex="0" aria-label="Help"></i>
    </ChildContent>
    <Content><b>Tip:</b> press Ctrl+K to search.</Content>
</AstrolTooltip>
```

**Tip:** press Ctrl+K to search.

### Supported parameters

- ChildContent **(RenderFragment)**, the element that carries the help.
- Text **(string)**, help text, or Content **(RenderFragment)** for your own content.
- Placement **(AstrolTooltipPlacement)**, **Top** (default), **Bottom**, **Left** or **Right**.
- Delay **(int)**, wait in milliseconds on hover (default **300**).
- Class **(string)**, css class of the wrapper.

A standalone icon needs **tabindex="0"** and **aria-label** to be reachable by keyboard. On icon-only buttons also set their **aria-label**: the tooltip is extra help, not their name.


---

# UploadFile

> AstrolUploadFile is a Blazor component that provides the logic for browsing files in the explorer, copying and pasting, as well as dragging and dropping files into the defined area. It also allows for the removal of uploaded files before they are saved.

Source page: https://doc.astrolui.com/basic-component/upload-file

## 1. Demo AstrolUploadFile

In this example, [notifications](/basic-component/notification) and [buttons](/basic-component/button) are implemented, so it is recommended to refer to the respective documentation.

The **AstrolUploadFile** component provides the logic for **browsing files in the explorer, copying and pasting, as well as dragging and dropping** files into the defined area. It also allows for **deleting** uploaded files before they are saved.

```razor
@using Astrol.Component.Basic.Button
@using Astrol.Component.Basic.UploadFile
@using Astrol.Entities.Basic.Static.Notification
@using Astrol.Entities.Basic.UI
@using Astrol.JSInterop.Base
@inject AstrolJSInterop jsI

<AstrolButton OnClick="_=>ChangeStatus(true)"
              Icon="astrol-upload-cloud"
              Text="Upload file"
              Style="AstrolStyle.Blue" />
<AstrolUploadFile Status="@_statusUpload"
                  SupportedExtensions="@(new List<string> {".jpg",".svg",".png",".pdf",".xlsx"})"
                  Save="SaveFile"
                  OnClose="ChangeStatus" />
<!-- Texts are optional (they follow the app language), e.g. Title="Upload file" TextSave="Save" -->
@code {
```

```csharp
   private bool _statusUpload = false;
   private async Task SaveFile(List<IBrowserFile> files) {
       ChangeStatus(false);
       await jsI.Notification($"Attaching {files.Count} file(s).".NotificationSuccess("astrol-upload-cloud", false));
   }
   private void ChangeStatus(bool newStatus) {
       _statusUpload = newStatus;
   }
}
```

### Supported parameters

- Status **(bool)**, visibility of the upload modal.
- OnClose **(EventCallback<bool>)**, raised with **false** when the modal closes (Close button, X, click outside or **Esc**); update your state variable here.
- Save **(EventCallback<List<IBrowserFile>>)**, raised when Save is pressed, with the selected files (the button is enabled when there is at least one). The modal does not close by itself: close it in this event. If the event throws, its message is shown as an error notification.
- Draggable **(bool)**, the modal can be moved (default **true**).
- Resizable **(bool)**, the modal can be resized (default **false**).
- Outline **(bool)**, outline style for the modal and its buttons (default **false**).
- MultipleFile **(bool)**, allows several files; when false, each new file replaces the previous one (default **true**).
- MaxNumberOfFiles **(int)**, maximum number of files (default **10**).
- MaxFileSize **(long)**, maximum size per file, in the unit set in **TypeStorage** (default **5**).
- TypeStorage **(TypeStorage)**, unit of **MaxFileSize** (default **TypeStorage.Megabyte**): Byte, Kilobyte, Megabyte, Gigabyte, Terabyte, Petabyte (**@using Astrol.Entities.Basic.Enums**).
- SupportedExtensions **(List<string>)**, allowed extensions including the dot (e.g. **".pdf"**), case-insensitive; they also filter the file browser. **If not set, any file is allowed**.
- IconLoad **(string)**, loading icon (default **astrol-spin1**).
- Title, TextClose, TextSave **(string)**, modal title and button texts.
- TextBrowse **(string)**, drop zone text; TextFileName and TextFileSize **(string)**, name and size labels of each file.
- TextErrorMaximumNumberFilesAccepted, TextErrorWrongFileExtension, TextErrorFileTooBig **(string)**, error messages.
- All texts are optional: by default they follow the app language.
- Besides browsing and drag and drop, files can be **pasted** (Ctrl+V) into the drop zone.
- **AstrolUploadFileEmbedded**: the same drop zone without modal or Save button. It accepts MultipleFile, MaxNumberOfFiles, MaxFileSize, TypeStorage, SupportedExtensions, IconLoad, TextBrowse, TextFileName, TextFileSize and the error texts, plus:
  - OnChange **(EventCallback<List<IBrowserFile>>)**, receives the full list of files every time one is added or removed.
  - CopyZone **(ElementReference?)**, element that receives pastes (defaults to the component itself).

## 2. Demo AstrolUploadFileEmbedded

```razor
@using Astrol.Component.Basic.UploadFile
@using Astrol.Entities.Basic.Static.Notification
@using Astrol.Entities.Basic.Enums
@using Astrol.Entities.Basic.UI
@using Astrol.JSInterop.Base
@inject AstrolJSInterop jsI

<AstrolUploadFileEmbedded MaxFileSize="5"
                          TypeStorage="TypeStorage.Megabyte"
                          MaxNumberOfFiles="10"
                          MultipleFile="true"
                          SupportedExtensions="@(new List<string> {".jpg",".png",".svg",".pdf",".xlsx"})"
                          OnChange="OnChange" />
@code {
```

```csharp
   private async Task OnChange(List<IBrowserFile> files) {
       await jsI.Notification($"Attaching {files.Count} file(s).".NotificationSuccess("astrol-upload-cloud", false));
   }
}
```


---

# AstrolBoard

> AstrolBoard: interactive Blazor board from AstrolUI with boxes you drag and resize, relations with vertices, zoom, mini-map, search, context menus, undo/redo and optional guides; smooth even with hundreds of elements.

Source page: https://doc.astrolui.com/board-component

**AstrolBoard<TBox, TRelation>** renders a **Board<TBox, TRelation>**: a list of boxes (**Box<TBox>**, with content of type **TBox**) and of relations between them (**Relation<TRelation>**). You decide how each box looks with **BoxRender**; the board changes position and size on the same object and raises **OnChangeBoard** so you can save it.

## 1. Minimal example

## 2. Data model

- **Board<TBox, TRelation>**: **Id** (string), **Scale** (float, zoom; 1 = 100%), **Boxes** (List<Box<TBox>>) and **Relations** (List<Relation<TRelation>>).
- **Box<TBox>**: **Id** (string, unique), **BOX_NAME** (text used by the search), **X**, **Y**, **Width**, **Height** (float, in board units without zoom), **Color** (color in the mini-map), **Content** (TBox, your data) and **ShowGuides** (bool?, guides for this box only).
- **Relation<TRelation>**: **BoxIdA** and **BoxIdB** (the boxes it joins; if they are the same a loop is drawn at its bottom-right corner), **Vertices** (List<Vertex>, intermediate points), **AnchorA** / **AnchorB** (BoxAnchor?, fixed point of each box where the line starts and ends), **Arrow** (RelationArrow?), **Label** (string) and **Content** (TRelation).
- **Vertex**: **Id**, **X**, **Y** and **Order** (the line goes through the vertices in that order).
- **Position**: **X**, **Y** (received by the menu events, in board pixels; divide by **Scale** to get model units).
- To add or remove boxes or relations, change the lists of the same **Board** object: the board detects it when it renders again and adds it to the history. If you assign another **Board** object, the board starts again (selection and history).

## 3. Mouse and keyboard

- **Drag a box**: moves it (and all the selected ones, with the vertices of the relations between them).
- **Drag a corner or side** of the box: resizes it, respecting **MinWidth** / **MinHeight**.
- **Drag a vertex**: bends the relation. **Drag the background**: scrolls the board.
- **Drag the end of a line** (with **EditAnchors**): fixes it to a point of the box border; double-click releases it.
- **Ctrl + click**: adds a box to or removes it from the selection. **Ctrl + A**: selects everything. **Esc**: clears the selection and closes menus.
- **Arrows**: move the selection 5 px (**Shift + arrows**: 20 px). **Delete**: raises **OnKeyDownDelete** or, when it is not used, deletes the selection and its relations.
- **Ctrl + C / V / D**: copy, paste and duplicate. **Drag a port** (AllowConnect): connect. **Shift + drag the background**: select with a rectangle.
- **Ctrl + Z**: undo. **Ctrl + Y** or **Ctrl + Shift + Z**: redo.
- **Ctrl + F**: search boxes by **BOX_NAME** (ignoring case and accents). **Ctrl + wheel**: zoom (20% to 300%).
- **Right click**: board, box, relation or vertex menu (when enabled).
- Shortcuts only act with the focus inside the board; right click and browser shortcuts keep working in the rest of the page, and they do not act while typing in a field inside a box.

## 4. Context menus

- Enable each menu with **ShowBoardContextMenu**, **ShowBoxContextMenu**, **ShowRelationContextMenu** or **ShowVertexContextMenu** and write its content in **BoardContextMenu**, **BoxContextMenu**, **RelationContextMenu** or **VertexContextMenu**.
- When it opens, **OnOpen…ContextMenu** gives you the id of the box, of the relation (**BoxIdA**, **BoxIdB**) or of the vertex and the click position in board pixels (divide by **Scale** to insert a box there). Store them and use them in the options.
- Inside the board the browser menu never opens: only the board, box, line or vertex menu appears.
- The menu closes when an option is chosen, with **Esc** or when clicking outside, and is placed so that it fits in the visible part of the board.
- **MenuOpion**: ready-made option with **Icon**, **IconColor** and **IconBackground** (optional; without them the icon is neutral), **Text**, **KeyboardShortcut**, **HasSeparator**, **Status** (false = disabled) and **OnClick**. Use **NeedAuthorize="false"** if you do not filter by roles (**Roles**). You can also use your own HTML with the **p-board-menu-option** class.

```razor
<AstrolBoard TBox="Task" TRelation="object" Board="board"
             ShowBoardContextMenu="true" ShowBoxContextMenu="true"
             OnOpenBoardContextMenu="p => { position = p; }"
             OnOpenBoxContextMenu="e => { (boxId, position) = e; }">
    <BoardContextMenu>
        <MenuOpion NeedAuthorize="false" Icon="astrol-plus" Text="New box here" OnClick="AddBox" />
    </BoardContextMenu>
    <BoxContextMenu>
        <MenuOpion NeedAuthorize="false" Icon="astrol-clone" Text="Duplicate" OnClick="Duplicate" HasSeparator="true" />
        <MenuOpion NeedAuthorize="false" Icon="astrol-trash" IconColor="var(--aui-danger)" Text="Delete" OnClick="Delete" />
    </BoxContextMenu>
    ...
</AstrolBoard>
```

```csharp
private Position position = new();
private string? boxId;

// The position is in board pixels: divide by Scale to get model units
private void AddBox() => board.Boxes.Add(new Box<Task> { X = position.X / board.Scale, Y = position.Y / board.Scale, BOX_NAME = "New" });
private void Delete() => board.Boxes.RemoveAll(b => b.Id == boxId);
```

## 5. Line anchors

- **RelationAnchor** (board parameter): **Center** (default, lines go from center to center) or **Border** (they start and end at the border of the boxes, in the direction of the other end or of the nearest vertex).
- **Relation.AnchorA** / **AnchorB** (**BoxAnchor**, optional): a fixed point of each box, relative to it (**X** and **Y** from 0 to 1). Shortcuts: **BoxAnchor.Top**, **Right**, **Bottom**, **Left**, **Center**. When it is **null**, **RelationAnchor** is used.
- **LineStyle** (board parameter): **Straight** (default, straight segments) or **Curved** (smooth curves that leave perpendicular to the side of the box and go through the vertices).
- **EditAnchors** (board parameter): when hovering a line or a box the circles at its ends appear, drawn over the box (they take priority over the resize handles: if they match, move the end first); the user drags the end of a line to a point of the border (it snaps to corners, quarters and middles of the sides) and the point is stored in **AnchorA** / **AnchorB**; double-click on the end releases it. It goes into the history (Ctrl+Z) and raises **OnChangeBoard**.
- A relation of a box with itself (**BoxIdA** = **BoxIdB**) is drawn as a loop at its bottom-right corner.

```razor
<AstrolBoard TBox="Task" TRelation="object" Board="board"
             RelationAnchor="RelationAnchor.Border"
             LineStyle="RelationLineStyle.Curved"
             EditAnchors="true"> ... </AstrolBoard>
```

```csharp
// From the middle of the right side of A to the top quarter of the left side of B
board.Relations.Add(new Relation<object>
{
    BoxIdA = a.Id,
    BoxIdB = b.Id,
    AnchorA = BoxAnchor.Right,           // (1, 0.5)
    AnchorB = new BoxAnchor(0, 0.25F),   // x and y from 0 to 1, relative to the box
});
```

## 6. Editing tools

- **Arrows**: **RelationArrow** (board parameter: **None**, **End** A → B, **Start** A ← B, **Both**) and **Relation.Arrow** for a single relation. An end with an arrow goes to the border of the box even in center mode.
- **Labels**: **Relation.Label** (text) or **RelationRender** (**RenderFragment<Relation>**, any content), centered at half the length of the line or curve. Right-click on the label = relation menu.
- **Connect by dragging**: **AllowConnect**. Hovering a box shows four ports outside it; drag one to another box (it is highlighted) and drop. **OnConnect** (**BoardConnectEventArgs**) receives the relation before it is added to complete it (**Content**, **Label**, **Arrow**…) or cancel it (**Cancel = true**).
- **Rectangle selection**: **BackgroundDrag** = **Pan** (default, dragging the background scrolls and with Shift selects) or **Select** (the other way round). Ctrl adds to the selection.
- **Snapping**: **SnapToGrid** (grid size, 0 = off) when moving and resizing, and **SnapToBoxes**: when moving, the box aligns with the edges and centers of the others (within 6 px) and the guide is drawn.
- **Clipboard** (**AllowClipboard**, default **true**): Ctrl+C, Ctrl+V (moved 20 px each time) and Ctrl+D copy the selected boxes with the relations between them; the copies stay selected and raise **OnBoxesAdded**. The content is copied with **CloneBox** / **CloneRelation** or, when not given, through JSON (if that is not possible, the reference is shared).
- **Delete**: if you use **OnKeyDownDelete**, your code decides (as before); otherwise the selection and its relations are removed and **OnBoxesRemoved** is raised.
- Methods for your menus: **CopySelection()**, **PasteAsync()**, **DuplicateSelectionAsync()**, **DeleteSelectionAsync()**. Everything goes into the history (Ctrl+Z) and raises **OnChangeBoard**.

```razor
<AstrolBoard TBox="Task" TRelation="object" Board="board" @ref="boardRef"
             RelationAnchor="RelationAnchor.Border"
             RelationArrow="RelationArrow.End"
             AllowConnect="true" OnConnect="Connect"
             BackgroundDrag="BoardBackgroundDrag.Select"
             SnapToGrid="20" SnapToBoxes="true"
             OnBoxesAdded="Added" OnBoxesRemoved="Removed">
    <RelationRender>@context.Label</RelationRender>
    ...
</AstrolBoard>
```

```csharp
// The relation is not on the board yet: complete it or cancel it
private void Connect(BoardConnectEventArgs<object> e)
{
    e.Relation.Label = "next";
    e.Cancel = board.Relations.Any(r => r.BoxIdA == e.Relation.BoxIdA && r.BoxIdB == e.Relation.BoxIdB);
}

board.Relations.Add(new Relation<object> { BoxIdA = a.Id, BoxIdB = b.Id, Label = "Yes", Arrow = RelationArrow.Both });
```

## 7. Automatic arrangement

- **ArrangeAsync(BoardLayoutOptions?)** (with **@ref**) orders the board by layers following the direction of the relations (from **BoxIdA** to **BoxIdB**): it breaks cycles, reduces line crossings and aligns each box with its neighbors. Groups that are not connected are placed side by side and boxes without relations at the end.
- Relations that skip layers get vertices to go around the boxes; the others are straight (their vertices are removed). With **UseVertices = false** all of them are removed.
- **It never adds, removes or changes relations** (boxes, content, anchors) nor the size of the boxes: it only moves boxes and vertices. It goes into the history (Ctrl+Z) and raises **OnChangeBoard**.
- **BoardLayoutOptions**: **Direction** (**TopToBottom** or **LeftToRight**), **LayerSpacing** (80), **BoxSpacing** (40), **GroupSpacing** (80), **UseVertices** (true), **Left**/**Top** (20, never less than MinLeft/MinTop), **MaxWidth** (1600, width of each row of groups; limited to MaxRight) and **Animate** (true).
- **BoardLayout.Arrange(board, options)** does the same without the component (e.g. when you create the board or on the server).

```razor
<button @onclick="Arrange">Arrange</button>
<AstrolBoard TBox="Task" TRelation="object" Board="board" @ref="boardRef"> ... </AstrolBoard>
```

```csharp
private AstrolBoard<Task, object>? boardRef;

private Task Arrange() => boardRef!.ArrangeAsync(new BoardLayoutOptions
{
    Direction = BoardLayoutDirection.LeftToRight,
    LayerSpacing = 60,
});

// Without the component (e.g. before showing the board):
BoardLayout.Arrange(board);
```

## 8. Guides while dragging (ShowGuides)

With **ShowGuides="true"**, while dragging or resizing the selected box, dashed guide lines appear from its corners (outwards) and from the middle of its sides (fainter), up to the edge of the board, to align it with other boxes. They are off by default. Each box can force them with **Box.ShowGuides** (**true** / **false**; **null** follows the board). The look is changed with CSS variables:

```razor
<AstrolBoard TBox="Task" TRelation="object" Board="board" ShowGuides="true"> ... </AstrolBoard>
```

```csharp
// Per box: null = follow the board, true / false = force it for this box
board.Boxes.Add(new Box<Task> { BOX_NAME = "Title", ShowGuides = false });
```

```css
/* Optional: line style, separation and opacity of the side lines */
:root {
    --border-line: 1px dashed var(--color-red-transparent);
    --pbse-offset: 2px;
    --pbse-side-opacity: 0.45;
}
```

## 9. Performance

- Dragging, resizing, moving vertices, scrolling the board and the mini-map happen in the browser, one paint per frame: **no calls to .NET while you drag** (a single one on release). In Blazor Server nothing travels over the network during the drag.
- When a change is committed, only the boxes and relations that changed are rendered again.
- Nothing is initialized per box: with 500 boxes the board mounts in half the time it used to and each drag step goes from ~360 ms to ~2 ms.
- The history only stores geometry (it does not copy your **TBox** content).
- If your **BoxRender** is expensive, keep it simple or use your own components: it renders again when the board's parent renders again.

### Supported parameters

- Board **(Board<TBox, TRelation>)**, the board to render **(required)**.
- BoxRender **(RenderFragment<Box<TBox>>)**, content of each box; **context** is the box.
- BackgroundType **(BackgroundType)**, background: **None**, **Grids** (default), **Points** or **Quadrants**.
- ShowGuides **(bool)**, guides while dragging (default **false**).
- ShowSearch, ShowZoom **(bool)**, search and zoom with mini-map (default **true**); ZoomStatus **(bool)**, mini-map open; EnableZoom and AllowChangeScale **(bool)**, allow zooming with the wheel and with the buttons.
- MinWidth, MinHeight **(float)**, minimum box size (default **100**); MinLeft, MinTop **(float)** (default **10**), MaxRight, MaxBottom **(float)**, area where boxes can move.
- RelationAnchor **(RelationAnchor)**, lines start at the center (**Center**, default) or at the border (**Border**) of the boxes. LineStyle **(RelationLineStyle)**, straight (**Straight**, default) or curved (**Curved**) lines. EditAnchors **(bool)**, the user fixes the ends by dragging them.
- RelationArrow **(RelationArrow)**, arrows; RelationRender **(RenderFragment<Relation>)**, labels. AllowConnect **(bool)** and OnConnect **(BoardConnectEventArgs)**, connect by dragging. BackgroundDrag **(BoardBackgroundDrag)**, scroll or select. SnapToGrid **(float)**, SnapToBoxes **(bool)**, snapping. AllowClipboard **(bool)**, CloneBox, CloneRelation **(Func)**, OnBoxesAdded, OnBoxesRemoved.
- DiscontinueLine **(bool)**, dashed relation lines. BoxDelay **(bool)**, smooth transition when moving with the keyboard or undoing.
- LongMemory **(int)**, history states (default **10**; **0** turns it off).
- ShowBoardContextMenu, ShowBoxContextMenu, ShowRelationContextMenu, ShowVertexContextMenu **(bool)** and BoardContextMenu, BoxContextMenu, RelationContextMenu, VertexContextMenu **(RenderFragment)**, right-click menus (use **MenuOpion** or the **p-board-menu-option** class on the options).
- LoadComponent **(RenderFragment)**, loading indicator. TextPlaceholderSearch, AriaLabel **(string)**, CssClass, CssStyle **(string)**.
- OnChangeBoard **(EventCallback<Board>)**, after every user change (move, resize, anchor a line, arrows, undo).
- OnOpenBoardContextMenu **(Position)**, OnOpenBoxContextMenu **((string, Position))**, OnOpenRelationContextMenu **((string, string, Position))**, OnOpenVertexContextMenu **((string, Position))** and OnChange…ContextMenuStatus **(bool)**.
- OnDobleClickBox **(Box<TBox>)**, OnKeyDownDelete, OnChangeScale **(float)**, OnChangeZoomStatus **(bool)**.

### Public methods

With **@ref** (**private AstrolBoard<Task, object>? boardRef;**):

- **ArrangeAsync(options)**: orders every box by its relations (see «Automatic arrangement»).
- **CopySelection()**, **PasteAsync()**, **DuplicateSelectionAsync()**, **DeleteSelectionAsync()**: clipboard and deleting the selection.
- **UndoAsync()** / **RedoAsync()**: undo and redo.
- **GetHistoryInfo()**: **CanUndo**, **CanRedo**, **CurrentIndex**, **TotalStates**. **ClearHistory()**: clears the history.
- **_idBoxesSelected**: ids of the selected boxes. **RemoveItemSelected(ids)**: removes them from the selection.
- **GetSVGWidth()**: content width. **EndMoveBoxPosition()**: recalculates the size and raises **OnChangeBoard**.


---

# Board · Examples

> AstrolBoard: interactive Blazor board from AstrolUI with boxes you drag and resize, relations with vertices, zoom, mini-map, search, context menus, undo/redo and optional guides; smooth even with hundreds of elements.

Source page: https://doc.astrolui.com/board-example

Each example is a complete component: copy its code (markup and **@code**) with the sample data and replace it with yours.

## Basic board

Boxes with custom content (**BoxRender**) and relations. **OnChangeBoard** reports every change.

```razor
@using Astrol.Component.Board
@using Astrol.Entities.Basic.UI.Board

@* Drag the boxes, resize them from the corners, Ctrl+click to select several, arrows to move them,
   Ctrl+Z / Ctrl+Y, Ctrl+F to search and Ctrl+wheel to zoom. *@
<div style="height:380px">
    <AstrolBoard TBox="WorkItem" TRelation="object"
                 Board="board"
                 BackgroundType="BackgroundType.Points"
                 MinWidth="80"
                 MinHeight="60"
                 OnChangeBoard="OnChange">
        <BoxRender>
            <div style="height:100%; padding:8px; border-radius:8px; border:1px solid var(--color-gray-a); background:var(--layout-menu-bg); overflow:hidden">
                <b>@context.BOX_NAME</b>
                <div style="font-size:.8em; opacity:.8">@context.Content.Owner</div>
            </div>
        </BoxRender>
    </AstrolBoard>
</div>
<p aria-live="polite">@message</p>

@code {
    private string message = "Move a box.";
    private readonly Board<WorkItem, object> board = Create();

    private void OnChange(Board<WorkItem, object> changed)
    {
        var first = changed.Boxes[0];
        message = $"{first.BOX_NAME}: X {first.X:0}, Y {first.Y:0}, {first.Width:0} x {first.Height:0}";
    }

    private static Board<WorkItem, object> Create()
    {
        var b = new Board<WorkItem, object>();
        b.Boxes.Add(new Box<WorkItem> { X = 30, Y = 40, Width = 160, Height = 90, BOX_NAME = "Design", Content = new WorkItem { Owner = "Ana" } });
        b.Boxes.Add(new Box<WorkItem> { X = 290, Y = 40, Width = 160, Height = 90, BOX_NAME = "Build", Content = new WorkItem { Owner = "Luis" } });
        b.Boxes.Add(new Box<WorkItem> { X = 290, Y = 220, Width = 160, Height = 90, BOX_NAME = "Test", Content = new WorkItem { Owner = "Eva" } });
        b.Relations.Add(new Relation<object> { BoxIdA = b.Boxes[0].Id, BoxIdB = b.Boxes[1].Id });
        b.Relations.Add(new Relation<object> { BoxIdA = b.Boxes[1].Id, BoxIdB = b.Boxes[2].Id });
        return b;
    }

    public class WorkItem
    {
        public string Owner { get; set; } = string.Empty;
    }
}
```

## Diagram editor

All the tools together: arrows and labels on the relations; hover a box and drag one of its four circles to another box to connect them; drag the background to select with a rectangle (Shift + drag scrolls); boxes snap to the grid and align with the others; Ctrl+C, Ctrl+V, Ctrl+D and Delete copy, paste, duplicate and delete (with their relations). Right-click on a line to change its arrows or its label.

```razor
@using Astrol.Component.Board
@using Astrol.Entities.Basic.UI.Board

@* A small diagram editor with the built-in tools:
   - Arrows (RelationArrow / Relation.Arrow) and labels (Relation.Label or RelationRender).
   - AllowConnect: hover a box and drag one of its four circles to another box; OnConnect completes the relation.
   - BackgroundDrag: drag the background to select with a rectangle (Shift + drag scrolls) or the other way round.
   - SnapToGrid / SnapToBoxes: boxes snap to a 20 px grid and align with the edges and centers of the others.
   - Ctrl+C / Ctrl+V / Ctrl+D copy, paste and duplicate (with the relations between them); Delete removes the
     selection and its relations (when OnKeyDownDelete is not used). Ctrl+Z undoes everything. *@
<div class="diagram-options">
    <button type="button" class="@(dragSelect ? "on" : null)" @onclick="() => dragSelect = !dragSelect">Drag selects</button>
    <button type="button" class="@(snap ? "on" : null)" @onclick="() => snap = !snap">Snap</button>
    <button type="button" class="@(curved ? "on" : null)" @onclick="() => curved = !curved">Curved</button>
    <span class="diagram-hint">@hint</span>
</div>
<div style="height:440px">
    <AstrolBoard TBox="string" TRelation="object"
                 @ref="boardRef"
                 Board="board"
                 RelationAnchor="RelationAnchor.Border"
                 RelationArrow="RelationArrow.End"
                 LineStyle="@(curved ? RelationLineStyle.Curved : RelationLineStyle.Straight)"
                 AllowConnect="true"
                 EditAnchors="true"
                 BackgroundDrag="@(dragSelect ? BoardBackgroundDrag.Select : BoardBackgroundDrag.Pan)"
                 SnapToGrid="@(snap ? 20 : 0)"
                 SnapToBoxes="snap"
                 MinWidth="60" MinHeight="40"
                 ShowBoardContextMenu="true"
                 ShowBoxContextMenu="true"
                 ShowRelationContextMenu="true"
                 OnOpenBoardContextMenu="p => { position = p; }"
                 OnOpenRelationContextMenu="e => { (relationA, relationB, _) = e; }"
                 OnConnect="Connect"
                 OnBoxesAdded="Added"
                 OnBoxesRemoved="Removed">
        <BoardContextMenu>
            <MenuOpion NeedAuthorize="false" Icon="astrol-plus" Text="New box here" OnClick="AddBox" />
            <MenuOpion NeedAuthorize="false" Icon="astrol-paste" Text="Paste" KeyboardShortcut="Ctrl+V" OnClick="() => boardRef!.PasteAsync()" />
        </BoardContextMenu>
        <BoxContextMenu>
            <MenuOpion NeedAuthorize="false" Icon="astrol-docs" Text="Copy" KeyboardShortcut="Ctrl+C" OnClick="() => boardRef!.CopySelection()" />
            <MenuOpion NeedAuthorize="false" Icon="astrol-clone" Text="Duplicate" KeyboardShortcut="Ctrl+D" OnClick="() => boardRef!.DuplicateSelectionAsync()" HasSeparator="true" />
            <MenuOpion NeedAuthorize="false" Icon="astrol-trash" IconColor="var(--aui-danger)" Text="Delete" KeyboardShortcut="Supr" OnClick="() => boardRef!.DeleteSelectionAsync()" />
        </BoxContextMenu>
        <RelationContextMenu>
            <MenuOpion NeedAuthorize="false" Icon="astrol-forward" Text="Arrow A → B" OnClick="() => SetArrow(RelationArrow.End)" />
            <MenuOpion NeedAuthorize="false" Icon="astrol-resize-horizontal" Text="Arrows A ↔ B" OnClick="() => SetArrow(RelationArrow.Both)" />
            <MenuOpion NeedAuthorize="false" Icon="astrol-minus" Text="No arrows" OnClick="() => SetArrow(RelationArrow.None)" HasSeparator="true" />
            <MenuOpion NeedAuthorize="false" Icon="astrol-ok" Text="Label «Yes»" OnClick="@(() => SetLabel("Yes"))" />
            <MenuOpion NeedAuthorize="false" Icon="astrol-cancel" Text="Label «No»" OnClick="@(() => SetLabel("No"))" />
            <MenuOpion NeedAuthorize="false" Icon="astrol-minus" Text="Remove label" OnClick="@(() => SetLabel(null))" HasSeparator="true" />
            <MenuOpion NeedAuthorize="false" Icon="astrol-unlink" IconColor="var(--aui-danger)" Text="Delete relation" OnClick="DeleteRelation" />
        </RelationContextMenu>
        <BoxRender>
            <div class="diagram-box @(context.Content)">@context.BOX_NAME</div>
        </BoxRender>
    </AstrolBoard>
</div>

<style>
    .diagram-options {
        display: flex;
        flex-wrap: wrap;
        align-items: center;
        gap: 5px;
        margin-bottom: 5px;
    }

        .diagram-options button {
            padding: 4px 12px;
            border-radius: 5px;
            border: 1px solid var(--color-gray-a);
            background: var(--layout-menu-bg);
            color: inherit;
            cursor: pointer;
        }

            .diagram-options button.on {
                background: var(--color-base);
                border-color: var(--color-base);
                color: var(--color-dark);
            }

    .diagram-hint {
        margin-left: 8px;
        opacity: .8;
        font-size: .9em;
    }

    .diagram-box {
        height: 100%;
        display: flex;
        align-items: center;
        justify-content: center;
        text-align: center;
        border-radius: 8px;
        border: 1px solid var(--color-gray-a);
        background: var(--layout-menu-bg);
        font-size: .9em;
    }

        .diagram-box.start {
            border-radius: 999px;
            background: var(--color-base);
            color: var(--color-dark);
            border-color: var(--color-base);
        }

        .diagram-box.decision {
            border-style: dashed;
            border-color: var(--color-orange);
        }
</style>

@code {
    private AstrolBoard<string, object>? boardRef;
    private readonly Board<string, object> board = Create();
    private Position position = new();
    private string? relationA, relationB;
    private bool dragSelect = true;
    private bool snap = true;
    private bool curved;
    private string hint = "Hover a box and drag one of its circles to another box.";

    private Relation<object> Relation => board.Relations.First(r => r.BoxIdA == relationA && r.BoxIdB == relationB);

    // The relation is not on the board yet: complete it or cancel it.
    private void Connect(BoardConnectEventArgs<object> e)
    {
        if (board.Relations.Any(r => r.BoxIdA == e.Relation.BoxIdA && r.BoxIdB == e.Relation.BoxIdB))
        {
            e.Cancel = true;
            hint = "Those boxes are already connected.";
            return;
        }
        hint = "Relation added. Right-click on it to change its arrows or its label.";
    }

    private void Added(IReadOnlyList<Box<string>> boxes) => hint = $"{boxes.Count} box(es) added.";

    private void Removed(BoardRemovedEventArgs<string, object> e) =>
        hint = $"{e.Boxes.Count} box(es) and {e.Relations.Count} relation(s) removed.";

    private void AddBox()
    {
        board.Boxes.Add(new Box<string>
        {
            X = position.X / board.Scale,
            Y = position.Y / board.Scale,
            Width = 120,
            Height = 50,
            BOX_NAME = $"Step {board.Boxes.Count + 1}",
            Content = "",
        });
    }

    private void SetArrow(RelationArrow arrow) => Relation.Arrow = arrow;

    private void SetLabel(string? label) => Relation.Label = label!;

    private void DeleteRelation() => board.Relations.Remove(Relation);

    private static Board<string, object> Create()
    {
        var b = new Board<string, object>();
        void Box(string id, string name, float x, float y, string kind = "") =>
            b.Boxes.Add(new Box<string> { Id = id, X = x, Y = y, Width = 120, Height = 50, BOX_NAME = name, Content = kind });

        Box("start", "Start", 40, 40, "start");
        Box("check", "Is it valid?", 40, 160, "decision");
        Box("save", "Save", 280, 160);
        Box("fix", "Fix the data", 40, 300);
        Box("end", "End", 520, 160, "start");

        b.Relations.Add(new Relation<object> { BoxIdA = "start", BoxIdB = "check" });
        b.Relations.Add(new Relation<object> { BoxIdA = "check", BoxIdB = "save", Label = "Yes" });
        b.Relations.Add(new Relation<object> { BoxIdA = "check", BoxIdB = "fix", Label = "No" });
        b.Relations.Add(new Relation<object> { BoxIdA = "save", BoxIdB = "end" });
        b.Relations.Add(new Relation<object>
        {
            BoxIdA = "fix",
            BoxIdB = "check",
            AnchorA = BoxAnchor.Right,
            AnchorB = new BoxAnchor(1, 0.75F),
            Vertices = new List<Vertex> { new() { X = 200, Y = 325, Order = 1 }, new() { X = 200, Y = 197, Order = 2 } },
        });
        return b;
    }
}
```

## Board and box context menus

Right-click on the empty board (insert a box, paste, arrange) or on a box (color, copy, duplicate, connect, bring to front, delete); also on a line or a vertex. The options use **MenuOpion** (icon, text, shortcut, separator and disabled option).

```razor
@using Astrol.Component.Board
@using Astrol.Entities.Basic.UI.Board

@* Right-click on the empty board or on a box (also on a line or on a vertex). Each menu is a RenderFragment;
   MenuOpion is a ready-made option (icon, text, shortcut, separator, disabled). The events give the id and the
   click position in board pixels (divide by Scale to get model units). *@
<p style="margin:0 0 5px">@status</p>
<div style="height:400px">
    <AstrolBoard TBox="string" TRelation="object"
                 Board="board"
                 RelationAnchor="RelationAnchor.Border"
                 ShowBoardContextMenu="true"
                 ShowBoxContextMenu="true"
                 ShowRelationContextMenu="true"
                 ShowVertexContextMenu="true"
                 OnOpenBoardContextMenu="p => { position = p; }"
                 OnOpenBoxContextMenu="e => { (boxId, position) = e; }"
                 OnOpenRelationContextMenu="e => { (relationA, relationB, position) = e; }"
                 OnOpenVertexContextMenu="e => { (vertexId, position) = e; }">
        <BoardContextMenu>
            <MenuOpion NeedAuthorize="false" Icon="astrol-plus" Text="New box here" OnClick="AddBox" />
            <MenuOpion NeedAuthorize="false" Icon="astrol-paste" Text="Paste box" Status="copied != null" OnClick="Paste" HasSeparator="true" />
            <MenuOpion NeedAuthorize="false" Icon="astrol-sitemap" Text="Arrange in a row" OnClick="Arrange" />
        </BoardContextMenu>
        <BoxContextMenu>
            <div class="menu-colors">
                @foreach (var color in Colors)
                {
                    <button type="button" title="@color" style="background:@color" @onclick="() => SetColor(color)"></button>
                }
            </div>
            <MenuOpion NeedAuthorize="false" Icon="astrol-docs" Text="Copy" OnClick="Copy" />
            <MenuOpion NeedAuthorize="false" Icon="astrol-clone" Text="Duplicate" OnClick="Duplicate" />
            <MenuOpion NeedAuthorize="false" Icon="astrol-link" Text="Connect to the next box" OnClick="ConnectToNext" />
            <MenuOpion NeedAuthorize="false" Icon="astrol-level-up" Text="Bring to front" OnClick="BringToFront" HasSeparator="true" />
            <MenuOpion NeedAuthorize="false" Icon="astrol-trash" IconColor="var(--aui-danger)" Text="Delete" OnClick="DeleteBox" />
        </BoxContextMenu>
        <RelationContextMenu>
            <MenuOpion NeedAuthorize="false" Icon="astrol-plus" Text="Add vertex here" OnClick="AddVertex" />
            <MenuOpion NeedAuthorize="false" Icon="astrol-unlink" IconColor="var(--aui-danger)" Text="Delete relation" OnClick="DeleteRelation" />
        </RelationContextMenu>
        <VertexContextMenu>
            <MenuOpion NeedAuthorize="false" Icon="astrol-trash" IconColor="var(--aui-danger)" Text="Delete vertex" OnClick="DeleteVertex" />
        </VertexContextMenu>
        <BoxRender>
            <div style="height:100%; display:flex; align-items:center; justify-content:center; border-radius:8px; color:#fff; font-weight:600; background:@context.Color">
                @context.BOX_NAME
            </div>
        </BoxRender>
    </AstrolBoard>
</div>

<style>
    .menu-colors {
        display: flex;
        gap: 6px;
        padding: 4px 5px 8px;
    }

        .menu-colors button {
            width: 22px;
            height: 22px;
            border: 2px solid var(--color-white);
            border-radius: 50%;
            box-shadow: var(--shadow-control);
            cursor: pointer;
        }
</style>

@code {
    private static readonly string[] Colors = { "var(--color-base)", "var(--color-blue)", "var(--color-green)", "var(--color-orange)", "var(--color-red)" };

    private readonly Board<string, object> board = Create();
    private Position position = new();
    private string? boxId, relationA, relationB, vertexId;
    private Box<string>? copied;
    private string status = "Right-click on the board or on a box.";

    private Box<string> Selected => board.Boxes.First(b => b.Id == boxId);

    private void AddBox()
    {
        board.Boxes.Add(NewBox(position.X / board.Scale, position.Y / board.Scale, $"Box {board.Boxes.Count + 1}"));
        status = "Box added.";
    }

    private void Copy()
    {
        copied = Selected;
        status = $"\"{copied.BOX_NAME}\" copied: right-click on the board to paste it.";
    }

    private void Paste()
    {
        var box = NewBox(position.X / board.Scale, position.Y / board.Scale, copied!.BOX_NAME + " (copy)");
        box.Color = copied.Color;
        box.Width = copied.Width;
        box.Height = copied.Height;
        board.Boxes.Add(box);
        status = "Box pasted.";
    }

    private void Duplicate()
    {
        var source = Selected;
        var box = NewBox(source.X + 20, source.Y + 20, source.BOX_NAME + " (copy)");
        box.Color = source.Color;
        board.Boxes.Add(box);
        status = "Box duplicated.";
    }

    private void SetColor(string color)
    {
        Selected.Color = color;
        status = $"Color of \"{Selected.BOX_NAME}\" changed.";
    }

    // The last box of the list is painted on top.
    private void BringToFront()
    {
        var box = Selected;
        board.Boxes.Remove(box);
        board.Boxes.Add(box);
        status = $"\"{box.BOX_NAME}\" brought to front.";
    }

    private void Arrange()
    {
        float x = 30;
        foreach (var box in board.Boxes)
        {
            box.X = x;
            box.Y = 40;
            x += box.Width + 30;
        }
        status = "Boxes arranged.";
    }

    private void DeleteBox()
    {
        board.Boxes.RemoveAll(b => b.Id == boxId);
        board.Relations.RemoveAll(r => r.BoxIdA == boxId || r.BoxIdB == boxId);
        status = "Box deleted (Ctrl+Z restores it).";
    }

    private void ConnectToNext()
    {
        var index = board.Boxes.FindIndex(b => b.Id == boxId);
        var next = board.Boxes[(index + 1) % board.Boxes.Count];
        if (next.Id != boxId && !board.Relations.Any(r => r.BoxIdA == boxId && r.BoxIdB == next.Id))
        {
            board.Relations.Add(new Relation<object> { BoxIdA = boxId!, BoxIdB = next.Id });
            status = "Relation added.";
        }
    }

    private void AddVertex()
    {
        var relation = board.Relations.First(r => r.BoxIdA == relationA && r.BoxIdB == relationB);
        relation.Vertices.Add(new Vertex
        {
            X = position.X / board.Scale,
            Y = position.Y / board.Scale,
            Order = relation.Vertices.Count + 1,
        });
        status = "Vertex added: drag it to bend the line.";
    }

    private void DeleteRelation()
    {
        board.Relations.RemoveAll(r => r.BoxIdA == relationA && r.BoxIdB == relationB);
        status = "Relation deleted.";
    }

    private void DeleteVertex()
    {
        foreach (var relation in board.Relations)
        {
            relation.Vertices.RemoveAll(v => v.Id == vertexId);
        }
        status = "Vertex deleted.";
    }

    private static Box<string> NewBox(float x, float y, string name) =>
        new() { X = x, Y = y, Width = 120, Height = 70, BOX_NAME = name, Content = "" };

    private static Board<string, object> Create()
    {
        var b = new Board<string, object>();
        b.Boxes.Add(NewBox(40, 60, "Box 1"));
        b.Boxes.Add(NewBox(320, 60, "Box 2"));
        b.Boxes.Add(NewBox(180, 240, "Box 3"));
        b.Boxes[1].Color = "var(--color-blue)";
        b.Boxes[2].Color = "var(--color-green)";
        b.Relations.Add(new Relation<object> { BoxIdA = b.Boxes[0].Id, BoxIdB = b.Boxes[1].Id });
        return b;
    }
}
```

## Line anchors and shape

**RelationAnchor** chooses whether lines start at the center or at the border of the boxes and **LineStyle** whether they are straight or curved. With **EditAnchors**, hover a line or a box and drag the circle at the end (it is drawn over the box) to any point of the border; double-click releases it. «Done» has a relation with itself (a loop).

```razor
@using Astrol.Component.Board
@using Astrol.Entities.Basic.UI.Board

@* RelationAnchor: lines start at the center of the boxes (Center) or at their border (Border).
   LineStyle: straight lines (Straight) or smooth curves (Curved) that leave each box perpendicular to its side.
   Relation.AnchorA / AnchorB fix a point of each box (0..1, relative to the box).
   EditAnchors: hover a line or a box (selected or not) and drag the circle at the end of the line (drawn over the box) to any
   point of the border; it snaps to corners, quarters and middles. Double-click the circle to release it.
   The right-click menu of a line also sets them. "Done" has a relation with itself: a loop. *@
<div class="anchor-options">
    <button type="button" class="@(mode == RelationAnchor.Center ? "on" : null)" @onclick="() => mode = RelationAnchor.Center">Center</button>
    <button type="button" class="@(mode == RelationAnchor.Border ? "on" : null)" @onclick="() => mode = RelationAnchor.Border">Border</button>
    <span class="anchor-separator"></span>
    <button type="button" class="@(lineStyle == RelationLineStyle.Straight ? "on" : null)" @onclick="() => lineStyle = RelationLineStyle.Straight">Straight</button>
    <button type="button" class="@(lineStyle == RelationLineStyle.Curved ? "on" : null)" @onclick="() => lineStyle = RelationLineStyle.Curved">Curved</button>
    <span class="anchor-separator"></span>
    <button type="button" class="@(editAnchors ? "on" : null)" aria-pressed="@(editAnchors ? "true" : "false")" @onclick="() => editAnchors = !editAnchors">EditAnchors</button>
</div>
<div style="height:400px">
    <AstrolBoard TBox="string" TRelation="object"
                 Board="board"
                 RelationAnchor="mode"
                 LineStyle="lineStyle"
                 EditAnchors="editAnchors"
                 BackgroundType="BackgroundType.Points"
                 ShowRelationContextMenu="true"
                 OnOpenRelationContextMenu="e => { (relationA, relationB, _) = e; }">
        <RelationContextMenu>
            <MenuOpion NeedAuthorize="false" Icon="astrol-forward" Text="From the right to the left side" OnClick="() => Fix(BoxAnchor.Right, BoxAnchor.Left)" />
            <MenuOpion NeedAuthorize="false" Icon="astrol-down" Text="From the bottom to the top side" OnClick="() => Fix(BoxAnchor.Bottom, BoxAnchor.Top)" HasSeparator="true" />
            <MenuOpion NeedAuthorize="false" Icon="astrol-target" Text="Release (use the general mode)" OnClick="() => Fix(null, null)" />
        </RelationContextMenu>
        <BoxRender>
            <div style="height:100%; display:flex; align-items:center; justify-content:center; border-radius:8px; border:1px solid var(--color-gray-a); background:var(--layout-menu-bg)">
                @context.BOX_NAME
            </div>
        </BoxRender>
    </AstrolBoard>
</div>

<style>
    .anchor-options {
        display: flex;
        flex-wrap: wrap;
        gap: 5px;
        margin-bottom: 5px;
    }

        .anchor-options button {
            padding: 4px 12px;
            border-radius: 5px;
            border: 1px solid var(--color-gray-a);
            background: var(--layout-menu-bg);
            color: inherit;
            cursor: pointer;
        }

            .anchor-options button.on {
                background: var(--color-base);
                border-color: var(--color-base);
                color: var(--color-dark);
            }
    .anchor-separator {
        width: 1px;
        margin: 2px 4px;
        background: var(--color-gray-a);
    }
</style>

@code {
    private RelationAnchor mode = RelationAnchor.Border;
    private RelationLineStyle lineStyle = RelationLineStyle.Curved;
    private bool editAnchors = true;
    private string? relationA, relationB;
    private readonly Board<string, object> board = Create();

    private void Fix(BoxAnchor? a, BoxAnchor? b)
    {
        var relation = board.Relations.First(r => r.BoxIdA == relationA && r.BoxIdB == relationB);
        relation.AnchorA = a;
        relation.AnchorB = b;
    }

    private static Board<string, object> Create()
    {
        var b = new Board<string, object>();
        b.Boxes.Add(new Box<string> { X = 40, Y = 140, Width = 130, Height = 70, BOX_NAME = "Start", Content = "" });
        b.Boxes.Add(new Box<string> { X = 280, Y = 40, Width = 130, Height = 70, BOX_NAME = "Review", Content = "" });
        b.Boxes.Add(new Box<string> { X = 280, Y = 250, Width = 130, Height = 70, BOX_NAME = "Rework", Content = "" });
        b.Boxes.Add(new Box<string> { X = 520, Y = 140, Width = 130, Height = 70, BOX_NAME = "Done", Content = "" });

        // No anchors: they follow RelationAnchor (center or border)
        b.Relations.Add(new Relation<object> { BoxIdA = b.Boxes[0].Id, BoxIdB = b.Boxes[1].Id });
        b.Relations.Add(new Relation<object> { BoxIdA = b.Boxes[0].Id, BoxIdB = b.Boxes[2].Id });

        // Fixed anchors: from the right side of "Review" / "Rework" to the left side of "Done"
        b.Relations.Add(new Relation<object> { BoxIdA = b.Boxes[1].Id, BoxIdB = b.Boxes[3].Id, AnchorA = BoxAnchor.Right, AnchorB = new BoxAnchor(0, 0.25F) });
        b.Relations.Add(new Relation<object> { BoxIdA = b.Boxes[2].Id, BoxIdB = b.Boxes[3].Id, AnchorA = BoxAnchor.Right, AnchorB = new BoxAnchor(0, 0.75F) });

        // Fixed anchors: from the bottom of "Review" to the top of "Rework"
        b.Relations.Add(new Relation<object>
        {
            BoxIdA = b.Boxes[1].Id,
            BoxIdB = b.Boxes[2].Id,
            AnchorA = new BoxAnchor(0.75F, 1),
            AnchorB = new BoxAnchor(0.75F, 0),
        });

        // A relation of a box with itself: a loop at its bottom-right corner
        b.Relations.Add(new Relation<object> { BoxIdA = b.Boxes[3].Id, BoxIdB = b.Boxes[3].Id });
        return b;
    }
}
```

## Vertices with a context menu

Right-click on a line: add a vertex exactly where you clicked (in the right segment), draw a right-angle route or straighten it. Right-click on a vertex: align it with the previous point, snap it to the grid, duplicate it or delete it. Drag a vertex to move it.

```razor
@using Astrol.Component.Board
@using Astrol.Entities.Basic.UI.Board

@* Vertices bend a relation: the line goes through them in Order. Right-click on a line to add a vertex
   exactly where you clicked (between the right points), straighten it or route it with a right angle;
   right-click on a vertex to delete, duplicate, align or snap it to the grid. Drag a vertex to move it. *@
<p style="margin:0 0 5px">@status</p>
<div style="height:420px">
    <AstrolBoard TBox="string" TRelation="object"
                 Board="board"
                 RelationAnchor="RelationAnchor.Border"
                 ShowRelationContextMenu="true"
                 ShowVertexContextMenu="true"
                 OnOpenRelationContextMenu="e => { (relationA, relationB, position) = e; }"
                 OnOpenVertexContextMenu="e => { (vertexId, position) = e; }">
        <RelationContextMenu>
            <MenuOpion NeedAuthorize="false" Icon="astrol-plus" Text="Add vertex here" OnClick="AddVertex" HasSeparator="true" />
            <MenuOpion NeedAuthorize="false" Icon="astrol-flow-split" Text="Right-angle route" OnClick="RightAngle" />
            <MenuOpion NeedAuthorize="false" Icon="astrol-resize-horizontal" Text="Straighten (remove vertices)" Status="board.Relations.Any(r => r.BoxIdA == relationA && r.BoxIdB == relationB && r.Vertices.Count > 0)" OnClick="Straighten" />
        </RelationContextMenu>
        <VertexContextMenu>
            <MenuOpion NeedAuthorize="false" Icon="astrol-resize-horizontal" Text="Align horizontally with the previous point" OnClick="() => Align(horizontal: true)" />
            <MenuOpion NeedAuthorize="false" Icon="astrol-resize-vertical" Text="Align vertically with the previous point" OnClick="() => Align(horizontal: false)" />
            <MenuOpion NeedAuthorize="false" Icon="astrol-target" Text="Snap to the grid (20 px)" OnClick="Snap" HasSeparator="true" />
            <MenuOpion NeedAuthorize="false" Icon="astrol-clone" Text="Duplicate vertex" OnClick="Duplicate" />
            <MenuOpion NeedAuthorize="false" Icon="astrol-trash" IconColor="var(--aui-danger)" Text="Delete vertex" OnClick="Delete" />
        </VertexContextMenu>
        <BoxRender>
            <div style="height:100%; display:flex; align-items:center; justify-content:center; border-radius:8px; border:1px solid var(--color-gray-a); background:var(--layout-menu-bg)">
                @context.BOX_NAME
            </div>
        </BoxRender>
    </AstrolBoard>
</div>

@code {
    private readonly Board<string, object> board = Create();
    private Position position = new();
    private string? relationA, relationB, vertexId;
    private string status = "Right-click on a line or on a vertex.";

    private Relation<object> Relation => board.Relations.First(r => r.BoxIdA == relationA && r.BoxIdB == relationB);

    private Relation<object> RelationOfVertex => board.Relations.First(r => r.Vertices.Any(v => v.Id == vertexId));

    private Vertex SelectedVertex => RelationOfVertex.Vertices.First(v => v.Id == vertexId);

    private static (float X, float Y) Center(Box<string> box) => (box.X + box.Width / 2, box.Y + box.Height / 2);

    // Points of the line in order: box A, the vertices, box B.
    private List<(float X, float Y)> Points(Relation<object> relation)
    {
        var points = new List<(float X, float Y)> { Center(board.Boxes.First(b => b.Id == relation.BoxIdA)) };
        points.AddRange(relation.Vertices.OrderBy(v => v.Order).Select(v => (v.X, v.Y)));
        points.Add(Center(board.Boxes.First(b => b.Id == relation.BoxIdB)));
        return points;
    }

    private static void Renumber(Relation<object> relation, List<Vertex> ordered)
    {
        for (var i = 0; i < ordered.Count; i++)
        {
            ordered[i].Order = i + 1;
        }
        relation.Vertices = ordered;
    }

    private void AddVertex()
    {
        // The click position is in board pixels: divide by Scale to get model units.
        var x = position.X / board.Scale;
        var y = position.Y / board.Scale;
        var relation = Relation;
        var points = Points(relation);

        // Insert it in the segment closest to the click, so the line does not cross itself.
        var segment = Enumerable.Range(0, points.Count - 1).MinBy(i => Distance(points[i], points[i + 1], x, y));
        var ordered = relation.Vertices.OrderBy(v => v.Order).ToList();
        ordered.Insert(segment, new Vertex { X = x, Y = y });
        Renumber(relation, ordered);
        status = $"Vertex added ({ordered.Count} in this line). Drag it to bend the line.";
    }

    private void Straighten()
    {
        Relation.Vertices = new List<Vertex>();
        status = "Line straightened.";
    }

    private void RightAngle()
    {
        var relation = Relation;
        var a = Center(board.Boxes.First(b => b.Id == relation.BoxIdA));
        var b = Center(board.Boxes.First(b => b.Id == relation.BoxIdB));
        relation.Vertices = new List<Vertex> { new() { X = b.X, Y = a.Y, Order = 1 } };
        status = "Right-angle route: one vertex at the corner.";
    }

    private void Align(bool horizontal)
    {
        var relation = RelationOfVertex;
        var vertex = SelectedVertex;
        var points = Points(relation);
        var index = relation.Vertices.OrderBy(v => v.Order).ToList().IndexOf(vertex) + 1; // +1: points[0] is box A
        var previous = points[index - 1];
        if (horizontal)
        {
            vertex.Y = previous.Y;
        }
        else
        {
            vertex.X = previous.X;
        }
        status = horizontal ? "Vertex aligned horizontally." : "Vertex aligned vertically.";
    }

    private void Snap()
    {
        var vertex = SelectedVertex;
        vertex.X = MathF.Round(vertex.X / 20) * 20;
        vertex.Y = MathF.Round(vertex.Y / 20) * 20;
        status = $"Vertex snapped to ({vertex.X}, {vertex.Y}).";
    }

    private void Duplicate()
    {
        var relation = RelationOfVertex;
        var vertex = SelectedVertex;
        var ordered = relation.Vertices.OrderBy(v => v.Order).ToList();
        ordered.Insert(ordered.IndexOf(vertex) + 1, new Vertex { X = vertex.X + 30, Y = vertex.Y + 30 });
        Renumber(relation, ordered);
        status = "Vertex duplicated.";
    }

    private void Delete()
    {
        var relation = RelationOfVertex;
        Renumber(relation, relation.Vertices.Where(v => v.Id != vertexId).OrderBy(v => v.Order).ToList());
        status = "Vertex deleted (Ctrl+Z restores it).";
    }

    // Distance from (x, y) to the segment p-q.
    private static float Distance((float X, float Y) p, (float X, float Y) q, float x, float y)
    {
        var dx = q.X - p.X;
        var dy = q.Y - p.Y;
        var length = dx * dx + dy * dy;
        var t = length == 0 ? 0 : Math.Clamp(((x - p.X) * dx + (y - p.Y) * dy) / length, 0, 1);
        var cx = p.X + t * dx - x;
        var cy = p.Y + t * dy - y;
        return MathF.Sqrt(cx * cx + cy * cy);
    }

    private static Board<string, object> Create()
    {
        var b = new Board<string, object>();
        b.Boxes.Add(new Box<string> { X = 40, Y = 40, Width = 120, Height = 70, BOX_NAME = "Source", Content = "" });
        b.Boxes.Add(new Box<string> { X = 480, Y = 110, Width = 120, Height = 70, BOX_NAME = "Target", Content = "" });
        b.Boxes.Add(new Box<string> { X = 40, Y = 280, Width = 120, Height = 70, BOX_NAME = "Input", Content = "" });
        b.Boxes.Add(new Box<string> { X = 480, Y = 280, Width = 120, Height = 70, BOX_NAME = "Output", Content = "" });

        // A straight line, a line with two vertices and a right-angle route
        b.Relations.Add(new Relation<object> { BoxIdA = b.Boxes[0].Id, BoxIdB = b.Boxes[1].Id });
        b.Relations.Add(new Relation<object>
        {
            BoxIdA = b.Boxes[2].Id,
            BoxIdB = b.Boxes[3].Id,
            Vertices = new List<Vertex>
            {
                new() { X = 240, Y = 220, Order = 1 },
                new() { X = 400, Y = 380, Order = 2 },
            },
        });
        b.Relations.Add(new Relation<object>
        {
            BoxIdA = b.Boxes[0].Id,
            BoxIdB = b.Boxes[3].Id,
            Vertices = new List<Vertex> { new() { X = 100, Y = 235, Order = 1 }, new() { X = 540, Y = 235, Order = 2 } },
        });
        return b;
    }
}
```

## Arrange automatically

**ArrangeAsync** orders every box by its relations, by layers and with as few crossings as possible; long relations get vertices to go around the boxes. Press **Shuffle** to mess it up and arrange it again top to bottom or left to right; Ctrl+Z undoes it.

```razor
@using Astrol.Component.Board
@using Astrol.Entities.Basic.UI.Board

@* ArrangeAsync orders every box by its relations: by layers, with as few crossings as possible and each box
   aligned with its neighbors. Long relations get vertices so they go around the boxes. It only moves boxes and
   vertices (relations are never added, removed or changed), it goes into the history (Ctrl+Z) and raises
   OnChangeBoard. BoardLayout.Arrange(board, options) does the same without the component (e.g. on the server). *@
<div class="arrange-options">
    <button type="button" @onclick="() => Arrange(BoardLayoutDirection.TopToBottom)"><i class="astrol-down"></i> Arrange top to bottom</button>
    <button type="button" @onclick="() => Arrange(BoardLayoutDirection.LeftToRight)"><i class="astrol-forward"></i> Arrange left to right</button>
    <button type="button" class="@(useVertices ? "on" : null)" aria-pressed="@(useVertices ? "true" : "false")" @onclick="() => useVertices = !useVertices">UseVertices</button>
    <button type="button" @onclick="Shuffle"><i class="astrol-flow-cross"></i> Shuffle</button>
</div>
<div style="height:440px">
    <AstrolBoard TBox="string" TRelation="object"
                 @ref="boardRef"
                 Board="board"
                 RelationAnchor="RelationAnchor.Border"
                 MinWidth="60" MinHeight="40">
        <BoxRender>
            <div style="height:100%; display:flex; align-items:center; justify-content:center; border-radius:8px; border:1px solid var(--color-gray-a); background:var(--layout-menu-bg); font-size:.85em">
                @context.BOX_NAME
            </div>
        </BoxRender>
    </AstrolBoard>
</div>

<style>
    .arrange-options {
        display: flex;
        flex-wrap: wrap;
        gap: 5px;
        margin-bottom: 5px;
    }

        .arrange-options button {
            padding: 4px 12px;
            border-radius: 5px;
            border: 1px solid var(--color-gray-a);
            background: var(--layout-menu-bg);
            color: inherit;
            cursor: pointer;
        }

            .arrange-options button.on {
                background: var(--color-base);
                border-color: var(--color-base);
                color: var(--color-dark);
            }
</style>

@code {
    private AstrolBoard<string, object>? boardRef;
    private readonly Board<string, object> board = Create();
    private bool useVertices = true;

    private Task Arrange(BoardLayoutDirection direction) =>
        boardRef!.ArrangeAsync(new BoardLayoutOptions
        {
            Direction = direction,
            UseVertices = useVertices,
            LayerSpacing = 60,
            BoxSpacing = 30,
        });

    // Random positions and random vertices: a tangled board to arrange again.
    private void Shuffle()
    {
        var random = new Random();
        foreach (var box in board.Boxes)
        {
            box.X = 20 + random.Next(600);
            box.Y = 20 + random.Next(320);
        }
        foreach (var relation in board.Relations)
        {
            relation.Vertices = random.Next(3) == 0
                ? new List<Vertex> { new() { X = 20 + random.Next(600), Y = 20 + random.Next(320), Order = 1 } }
                : new List<Vertex>();
        }
    }

    private static Board<string, object> Create()
    {
        var b = new Board<string, object>();
        var names = new[] { "Request", "Validate", "Approve", "Reject", "Notify", "Pay", "Ship", "Invoice", "Close", "Audit", "Archive", "Help desk" };
        var random = new Random(3);
        foreach (var name in names)
        {
            b.Boxes.Add(new Box<string> { Id = name, X = 20 + random.Next(600), Y = 20 + random.Next(320), Width = 100, Height = 46, BOX_NAME = name, Content = "" });
        }

        void Link(string a, string c) => b.Relations.Add(new Relation<object> { BoxIdA = a, BoxIdB = c });
        Link("Request", "Validate");
        Link("Validate", "Approve");
        Link("Validate", "Reject");
        Link("Approve", "Pay");
        Link("Approve", "Notify");
        Link("Reject", "Notify");
        Link("Pay", "Ship");
        Link("Pay", "Invoice");
        Link("Ship", "Close");
        Link("Invoice", "Close");
        Link("Request", "Audit");    // long relation: it gets vertices
        Link("Close", "Archive");
        Link("Audit", "Archive");
        Link("Reject", "Request");   // cycle: it is drawn back up
        return b;
    }
}
```

## PowerPoint-like slides

A slide editor: each element (AstrolUI logo in the theme color, title, text, list, chart, shape) is a box with any content. Guides to align, 16:9 slide limits, double-click to edit a text, menus to insert, order and delete, and a preview that paints the same data without the board.

```razor
@using Astrol.Component.Board
@using Astrol.Entities.Basic.UI
@using Astrol.Entities.Basic.UI.Board

@* A slide editor in the style of PowerPoint: each element (image, title, text, list, chart, shape) is a box
   with any content. ShowGuides helps to align, MaxRight/MaxBottom keep everything inside the 16:9 slide,
   double-click edits a text and the menus insert, order and delete elements. "Preview" paints the same
   data without the board: the model is plain data you can save and show anywhere. *@
<div class="slide-toolbar">
    <button type="button" @onclick="() => Add(SlideKind.Title, 60, 60)"><i class="astrol-font"></i> Title</button>
    <button type="button" @onclick="() => Add(SlideKind.Text, 60, 160)"><i class="astrol-doc-text"></i> Text</button>
    <button type="button" @onclick="() => Add(SlideKind.Image, 500, 60)"><i class="astrol-picture"></i> Image</button>
    <button type="button" @onclick="() => Add(SlideKind.Chart, 500, 250)"><i class="astrol-chart-bar"></i> Chart</button>
    <button type="button" @onclick="() => Add(SlideKind.Shape, 360, 300)"><i class="astrol-target"></i> Shape</button>
    <button type="button" class="slide-preview-button" @onclick="() => preview = !preview">
        <i class="@(preview ? "astrol-edit" : "astrol-play")"></i> @(preview ? "Edit" : "Preview")
    </button>
</div>

@if (preview)
{
    <div class="slide-preview">
        <div class="slide-page">
            @foreach (var box in board.Boxes)
            {
                <div class="slide-item" style="@Position(box)">@Content(box)</div>
            }
        </div>
    </div>
}
else
{
    <div style="height:500px">
        <AstrolBoard TBox="SlideItem" TRelation="object"
                     Board="board"
                     CssClass="slide-board"
                     BackgroundType="BackgroundType.None"
                     ShowGuides="true"
                     ShowSearch="false"
                     ShowZoom="false"
                     AllowChangeScale="false"
                     MinLeft="20" MinTop="20" MaxRight="820" MaxBottom="470"
                     MinWidth="30" MinHeight="30"
                     ShowBoardContextMenu="true"
                     ShowBoxContextMenu="true"
                     OnOpenBoardContextMenu="p => { position = p; }"
                     OnOpenBoxContextMenu="e => { (boxId, position) = e; }"
                     OnDobleClickBox="b => { editingId = b.Content.Kind is SlideKind.Title or SlideKind.Text or SlideKind.List ? b.Id : null; }">
            <BoardContextMenu>
                <MenuOpion NeedAuthorize="false" Icon="astrol-font" Text="Insert title" OnClick="() => AddHere(SlideKind.Title)" />
                <MenuOpion NeedAuthorize="false" Icon="astrol-doc-text" Text="Insert text" OnClick="() => AddHere(SlideKind.Text)" />
                <MenuOpion NeedAuthorize="false" Icon="astrol-list-bullet" Text="Insert list" OnClick="() => AddHere(SlideKind.List)" />
                <MenuOpion NeedAuthorize="false" Icon="astrol-picture" Text="Insert AstrolUI logo" OnClick="() => AddHere(SlideKind.Image)" />
                <MenuOpion NeedAuthorize="false" Icon="astrol-chart-bar" Text="Insert chart" OnClick="() => AddHere(SlideKind.Chart)" />
                <MenuOpion NeedAuthorize="false" Icon="astrol-target" Text="Insert shape" OnClick="() => AddHere(SlideKind.Shape)" />
            </BoardContextMenu>
            <BoxContextMenu>
                <MenuOpion NeedAuthorize="false" Icon="astrol-pencil" Text="Edit text (double-click)" Status="IsText" OnClick="() => editingId = boxId" HasSeparator="true" />
                <MenuOpion NeedAuthorize="false" Icon="astrol-level-up" Text="Bring to front" OnClick="() => Order(true)" />
                <MenuOpion NeedAuthorize="false" Icon="astrol-level-down" Text="Send to back" OnClick="() => Order(false)" HasSeparator="true" />
                <MenuOpion NeedAuthorize="false" Icon="astrol-clone" Text="Duplicate" OnClick="Duplicate" />
                <MenuOpion NeedAuthorize="false" Icon="astrol-trash" IconColor="var(--aui-danger)" Text="Delete" OnClick="Delete" />
            </BoxContextMenu>
            <BoxRender>
                @if (editingId == context.Id)
                {
                    <textarea class="slide-editor slide-@context.Content.Kind.ToString().ToLowerInvariant()"
                              @bind="context.Content.Text"
                              @onblur="() => editingId = null"
                              @ref="editor"></textarea>
                }
                else
                {
                    @Content(context)
                }
            </BoxRender>
        </AstrolBoard>
    </div>
}

<style>
    .slide-toolbar {
        display: flex;
        flex-wrap: wrap;
        gap: 5px;
        margin-bottom: 5px;
    }

        .slide-toolbar button {
            padding: 4px 10px;
            border-radius: 5px;
            border: 1px solid var(--color-gray-a);
            background: var(--layout-menu-bg);
            color: inherit;
            cursor: pointer;
        }

    .slide-preview-button {
        margin-left: auto;
    }

    /* The 16:9 slide (800 x 450) inside the board */
    .slide-board .p-board-canvas::before {
        content: '';
        position: absolute;
        left: 20px;
        top: 20px;
        width: 800px;
        height: 450px;
        background: #fff;
        box-shadow: 0 4px 18px rgba(0, 0, 0, .25);
        border-radius: 4px;
        pointer-events: none;
    }

    .slide-board .p-box {
        color: #1d2330;
    }

    .slide-title {
        font-size: 1.9em;
        font-weight: 700;
        line-height: 1.1;
    }

    .slide-text {
        font-size: 1.1em;
        line-height: 1.4;
        color: #4a5160;
    }

    .slide-list {
        font-size: 1.1em;
        line-height: 1.6;
        margin: 0;
        padding-left: 1.3em;
    }

    .slide-editor {
        width: 100%;
        height: 100%;
        resize: none;
        border: 1px dashed var(--color-base);
        background: transparent;
        color: inherit;
        font-family: inherit;
        padding: 0;
    }

    .slide-chart {
        height: 100%;
        display: flex;
        align-items: flex-end;
        gap: 8%;
        padding: 0 4% 0;
        border-bottom: 2px solid #c9ced8;
        box-sizing: border-box;
    }

        .slide-chart div {
            flex: 1;
            border-radius: 4px 4px 0 0;
            background: linear-gradient(180deg, #ffc107, #ff8f00);
        }

    .slide-shape {
        width: 100%;
        height: 100%;
        border-radius: 50%;
        background: radial-gradient(circle at 30% 30%, #6fb6ff, #1565c0);
    }

    .slide-image {
        width: 100%;
        height: 100%;
        object-fit: contain;
        pointer-events: none;
    }

    .slide-preview {
        max-width: 100%;
        overflow: auto;
        padding: 10px;
    }

    /* Same coordinates as the board (without the 20px margin of the board) */
    .slide-page {
        position: relative;
        width: 800px;
        height: 450px;
        background: #fff;
        color: #1d2330;
        border-radius: 4px;
        box-shadow: 0 4px 18px rgba(0, 0, 0, .25);
        overflow: hidden;
        font-size: 15px;
    }

    .slide-item {
        position: absolute;
    }
</style>

@code {
    public enum SlideKind { Title, Text, List, Image, Chart, Shape }

    public sealed class SlideItem
    {
        public SlideKind Kind { get; set; }
        public string Text { get; set; } = "";
    }

    // The layout cascades the theme color: the logo follows it (logo-astrolui-yellow/green/blue/... .svg).
    [CascadingParameter(Name = "ThemeStyle")]
    public AstrolTheme Theme { get; set; }

    private string Logo => $"img/logos/logo-astrolui-{Theme.ToString().ToLowerInvariant()}.svg";

    private static readonly int[] Bars = { 35, 60, 45, 85, 70 };

    private readonly Board<SlideItem, object> board = Create();
    private Position position = new();
    private string? boxId;
    private string? editingId;
    private bool preview;
    private ElementReference editor;
    private string? focusedEditor;

    private bool IsText => board.Boxes.FirstOrDefault(b => b.Id == boxId)?.Content.Kind is SlideKind.Title or SlideKind.Text or SlideKind.List;

    private RenderFragment Content(Box<SlideItem> box) => __builder =>
    {
        switch (box.Content.Kind)
        {
            case SlideKind.Title:
                <div class="slide-title">@box.Content.Text</div>
                break;
            case SlideKind.Text:
                <div class="slide-text">@box.Content.Text</div>
                break;
            case SlideKind.List:
                <ul class="slide-list">
                    @foreach (var line in box.Content.Text.Split('\n', StringSplitOptions.RemoveEmptyEntries))
                    {
                        <li>@line</li>
                    }
                </ul>
                break;
            case SlideKind.Image:
                <img class="slide-image" src="@Logo" alt="AstrolUI" draggable="false" />
                break;
            case SlideKind.Chart:
                <div class="slide-chart">
                    @foreach (var bar in Bars)
                    {
                        <div style="height:@(bar)%"></div>
                    }
                </div>
                break;
            default:
                <div class="slide-shape"></div>
                break;
        }
    };

    private static string Position(Box<SlideItem> box) =>
        FormattableString.Invariant($"left:{box.X - 20}px; top:{box.Y - 20}px; width:{box.Width}px; height:{box.Height}px;");

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        // Focus the text editor once when it opens.
        if (editingId != null && focusedEditor != editingId)
        {
            focusedEditor = editingId;
            await editor.FocusAsync();
        }
        else if (editingId == null)
        {
            focusedEditor = null;
        }
    }

    private void AddHere(SlideKind kind) => Add(kind, position.X / board.Scale, position.Y / board.Scale);

    private void Add(SlideKind kind, float x, float y)
    {
        var (width, height, text) = kind switch
        {
            SlideKind.Title => (420F, 60F, "New title"),
            SlideKind.Text => (360F, 80F, "Double-click to edit this text."),
            SlideKind.List => (320F, 110F, "First point\nSecond point\nThird point"),
            SlideKind.Image => (240F, 100F, ""),
            SlideKind.Chart => (260F, 160F, ""),
            _ => (90F, 90F, ""),
        };
        board.Boxes.Add(new Box<SlideItem>
        {
            X = Math.Clamp(x, 20, 820 - width),
            Y = Math.Clamp(y, 20, 470 - height),
            Width = width,
            Height = height,
            BOX_NAME = kind.ToString(),
            Content = new SlideItem { Kind = kind, Text = text },
        });
    }

    // The last box of the list is painted on top.
    private void Order(bool front)
    {
        var box = board.Boxes.First(b => b.Id == boxId);
        board.Boxes.Remove(box);
        if (front)
        {
            board.Boxes.Add(box);
        }
        else
        {
            board.Boxes.Insert(0, box);
        }
    }

    private void Duplicate()
    {
        var source = board.Boxes.First(b => b.Id == boxId);
        board.Boxes.Add(new Box<SlideItem>
        {
            X = Math.Min(source.X + 20, 820 - source.Width),
            Y = Math.Min(source.Y + 20, 470 - source.Height),
            Width = source.Width,
            Height = source.Height,
            BOX_NAME = source.BOX_NAME,
            Content = new SlideItem { Kind = source.Content.Kind, Text = source.Content.Text },
        });
    }

    private void Delete() => board.Boxes.RemoveAll(b => b.Id == boxId);

    private static Board<SlideItem, object> Create()
    {
        var b = new Board<SlideItem, object>();
        void Item(SlideKind kind, float x, float y, float w, float h, string text = "") =>
            b.Boxes.Add(new Box<SlideItem>
            {
                X = x, Y = y, Width = w, Height = h,
                BOX_NAME = kind.ToString(),
                Content = new SlideItem { Kind = kind, Text = text },
            });

        Item(SlideKind.Shape, 700, 330, 110, 110);
        Item(SlideKind.Image, 50, 45, 260, 90);
        Item(SlideKind.Title, 50, 160, 460, 50, "Blazor components for .NET 10");
        Item(SlideKind.Text, 50, 220, 420, 60, "Fast, light and accessible: a board, charts, a PDF viewer, a rich text editor and more.");
        Item(SlideKind.List, 50, 300, 380, 110, "Drag, resize and align with guides\nRight-click to insert or order\nDouble-click a text to edit it");
        Item(SlideKind.Chart, 540, 140, 240, 170);
        return b;
    }
}
```

## Guides while dragging

**ShowGuides** on the board and **Box.ShowGuides** per box. Select a box and drag or resize it.

```razor
@using Astrol.Component.Board
@using Astrol.Component.Basic.Form
@using Astrol.Entities.Basic.UI.Board

@* ShowGuides draws guide lines from the selected box while you drag or resize it.
   Each box can override it with Box.ShowGuides (here "No guides" never shows them). *@
<div style="margin-bottom:5px">
    <AstrolCheckbox @bind-Value="showGuides" Text="ShowGuides" />
</div>
<div style="height:380px">
    <AstrolBoard TBox="string" TRelation="object"
                 Board="board"
                 ShowGuides="showGuides"
                 BackgroundType="BackgroundType.Grids">
        <BoxRender>
            <div style="height:100%; display:flex; align-items:center; justify-content:center; border-radius:8px; border:1px solid var(--color-gray-a); background:var(--layout-menu-bg)">
                @context.BOX_NAME
            </div>
        </BoxRender>
    </AstrolBoard>
</div>

@code {
    private bool showGuides = true;
    private readonly Board<string, object> board = Create();

    private static Board<string, object> Create()
    {
        var b = new Board<string, object>();
        b.Boxes.Add(new Box<string> { X = 60, Y = 60, Width = 140, Height = 90, BOX_NAME = "Drag me", Content = "" });
        b.Boxes.Add(new Box<string> { X = 300, Y = 170, Width = 140, Height = 90, BOX_NAME = "Me too", Content = "" });
        b.Boxes.Add(new Box<string> { X = 520, Y = 60, Width = 140, Height = 90, BOX_NAME = "No guides", Content = "", ShowGuides = false });
        return b;
    }
}
```

## Relations, vertices and backgrounds

Relations with draggable vertices, a relation of a box with itself, **DiscontinueLine** and the four **BackgroundType** values.

```razor
@using Astrol.Component.Board
@using Astrol.Component.Basic.Form
@using Astrol.Entities.Basic.UI.Board

@* Relations go from center to center. Vertices (in Order) bend the line and can be dragged.
   A relation of a box with itself draws a loop. DiscontinueLine draws dashed lines. *@
<div style="margin-bottom:5px">
    <AstrolCheckbox @bind-Value="dashed" Text="DiscontinueLine" />
    <select @bind="background" aria-label="BackgroundType" style="margin-left:15px">
        @foreach (var type in Enum.GetValues<BackgroundType>())
        {
            <option value="@type">@type</option>
        }
    </select>
</div>
<div style="height:380px">
    <AstrolBoard TBox="string" TRelation="object"
                 Board="board"
                 DiscontinueLine="dashed"
                 BackgroundType="background">
        <BoxRender>
            <div style="height:100%; display:flex; align-items:center; justify-content:center; border-radius:50%; border:2px solid var(--color-base); background:var(--layout-menu-bg)">
                @context.BOX_NAME
            </div>
        </BoxRender>
    </AstrolBoard>
</div>

@code {
    private bool dashed;
    private BackgroundType background = BackgroundType.Quadrants;
    private readonly Board<string, object> board = Create();

    private static Board<string, object> Create()
    {
        var b = new Board<string, object>();
        var start = new Box<string> { X = 40, Y = 140, Width = 100, Height = 100, BOX_NAME = "Start", Content = "" };
        var review = new Box<string> { X = 330, Y = 40, Width = 100, Height = 100, BOX_NAME = "Review", Content = "" };
        var end = new Box<string> { X = 600, Y = 160, Width = 100, Height = 100, BOX_NAME = "End", Content = "" };
        b.Boxes.AddRange(new[] { start, review, end });

        b.Relations.Add(new Relation<object> { BoxIdA = start.Id, BoxIdB = review.Id });
        b.Relations.Add(new Relation<object>
        {
            BoxIdA = review.Id,
            BoxIdB = end.Id,
            Vertices = new List<Vertex> { new() { X = 520, Y = 60, Order = 1 }, new() { X = 560, Y = 120, Order = 2 } },
        });
        b.Relations.Add(new Relation<object>
        {
            BoxIdA = start.Id,
            BoxIdB = end.Id,
            Vertices = new List<Vertex> { new() { X = 330, Y = 320, Order = 1 } },
        });
        b.Relations.Add(new Relation<object> { BoxIdA = review.Id, BoxIdB = review.Id }); // loop
        return b;
    }
}
```

## History (undo and redo)

**UndoAsync**, **RedoAsync** and **GetHistoryInfo** through **@ref**; boxes you add can also be undone.

```razor
@using Astrol.Component.Board
@using Astrol.Entities.Basic.UI.Board
@using Astrol.Component.Basic.Button
@using Astrol.Entities.Basic.UI

@* Every change (drag, resize, arrows, boxes added or removed by you) goes to the history.
   Ctrl+Z / Ctrl+Y, or UndoAsync / RedoAsync through @ref. LongMemory sets how many states are kept. *@
<div style="margin-bottom:5px">
    <AstrolButton Icon="astrol-ccw" Text="Undo" Style="AstrolStyle.Blue" Status="@info.CanUndo" OnClick="Undo" />
    <AstrolButton Icon="astrol-cw-1" Text="Redo" Style="AstrolStyle.Blue" Status="@info.CanRedo" OnClick="Redo" />
    <AstrolButton Icon="astrol-plus" Text="Add box" Style="AstrolStyle.Green" OnClick="AddBox" />
    <span style="margin-left:10px">State @(info.CurrentIndex + 1) / @info.TotalStates</span>
</div>
<div style="height:340px">
    <AstrolBoard @ref="boardRef"
                 TBox="string" TRelation="object"
                 Board="board"
                 LongMemory="20"
                 OnChangeBoard="_ => Refresh()">
        <BoxRender>
            <div style="height:100%; display:flex; align-items:center; justify-content:center; border-radius:8px; border:1px solid var(--color-gray-a); background:var(--layout-menu-bg)">
                @context.BOX_NAME
            </div>
        </BoxRender>
    </AstrolBoard>
</div>

@code {
    private AstrolBoard<string, object>? boardRef;
    private BoardHistoryInfo info = new();
    private readonly Board<string, object> board = new()
    {
        Boxes = new List<Box<string>>
        {
            new() { X = 40, Y = 40, Width = 130, Height = 80, BOX_NAME = "One", Content = "" },
            new() { X = 260, Y = 120, Width = 130, Height = 80, BOX_NAME = "Two", Content = "" },
        },
    };

    protected override void OnAfterRender(bool firstRender)
    {
        if (firstRender) Refresh();
    }

    private void Refresh()
    {
        info = boardRef?.GetHistoryInfo() ?? new BoardHistoryInfo();
        StateHasChanged();
    }

    private async Task Undo()
    {
        await boardRef!.UndoAsync();
        Refresh();
    }

    private async Task Redo()
    {
        await boardRef!.RedoAsync();
        Refresh();
    }

    private async Task AddBox()
    {
        board.Boxes.Add(new Box<string> { X = 40 + board.Boxes.Count * 30, Y = 230, Width = 130, Height = 80, BOX_NAME = $"Box {board.Boxes.Count + 1}", Content = "" });
        await Task.Yield(); // the board detects the new box on this render
        Refresh();
    }
}
```

## Limits and minimum size

**MinLeft**, **MinTop**, **MaxRight**, **MaxBottom**, **MinWidth** and **MinHeight** (the allowed area is marked with a dashed line).

```razor
@using Astrol.Component.Board
@using Astrol.Entities.Basic.UI.Board

@* Boxes can only move inside the area MinLeft-MaxRight / MinTop-MaxBottom (dashed) and cannot be smaller
   than MinWidth x MinHeight. The limits apply to the mouse, the arrows and the resize handles. *@
<div style="height:380px">
    <AstrolBoard TBox="string" TRelation="object"
                 Board="board"
                 CssClass="board-limits-area"
                 BackgroundType="BackgroundType.None"
                 ShowZoom="false"
                 MinLeft="20" MinTop="20" MaxRight="620" MaxBottom="320"
                 MinWidth="60" MinHeight="40">
        <BoxRender>
            <div style="height:100%; display:flex; align-items:center; justify-content:center; border-radius:8px; border:1px solid var(--color-gray-a); background:var(--layout-menu-bg)">
                @context.BOX_NAME
            </div>
        </BoxRender>
    </AstrolBoard>
</div>

<style>
    /* Only to show the limits in this example */
    .board-limits-area .p-board-canvas::before {
        content: '';
        position: absolute;
        left: 20px;
        top: 20px;
        width: 600px;
        height: 300px;
        border: 2px dashed var(--color-orange);
        border-radius: 8px;
        pointer-events: none;
    }
</style>

@code {
    private readonly Board<string, object> board = new()
    {
        Boxes = new List<Box<string>>
        {
            new() { X = 40, Y = 40, Width = 120, Height = 70, BOX_NAME = "Inside", Content = "" },
            new() { X = 400, Y = 200, Width = 160, Height = 90, BOX_NAME = "Also inside", Content = "" },
        },
    };
}
```


---

# Installation

> AstrolBoard: interactive Blazor board from AstrolUI with boxes you drag and resize, relations with vertices, zoom, mini-map, search, context menus, undo/redo and optional guides; smooth even with hundreds of elements.

Source page: https://doc.astrolui.com/board-installation

**Astrol.Component.Board** is a canvas for diagrams, flows, org charts or plans: you render each box's content with Blazor and the component takes care of dragging, resizing, drawing the relations, zoom and history. It works in **Blazor WebAssembly** and **Blazor Server** and has no external dependencies.

## 1. Install the package

From the [**AstrolUI NuGet**](https://nuget.astrolui.com/) (source **https://nuget.astrolui.com/v3/index.json**) or by referencing the project in your solution:

```html
dotnet add package Astrol.Component.Board

<!-- or in the .csproj -->
<PackageReference Include="Astrol.Component.Board" Version="10.0.13.*" />
```

## 2. Add the namespace

The component lives in **Astrol.Component.Board** and the models (**Board**, **Box**, **Relation**, **Vertex**, **Position**, **BackgroundType**) in **Astrol.Entities.Basic.UI.Board**:

```razor
@* _Imports.razor *@
@using Astrol.Component.Board
@using Astrol.Entities.Basic.UI.Board
```

## 3. Theme and scripts

**No script, stylesheet or service is needed**: the board loads its module and styles the first time it appears on screen (pages without a board download nothing). It no longer uses **interact.js**. For theme colors and dark mode, the app must include the [basic components](/basic-component/installation) stylesheet. If you are upgrading from an earlier version, remove these lines:

```html
<!-- AstrolUI theme (colors, light/dark mode), shared with the other components -->
<link href="_content/Astrol.Component.Basic/css/astrol-basic.min.css" rel="stylesheet" />

<!-- No longer needed (remove them if you are upgrading) -->
<link href="_content/Astrol.Component.Board/board.css" rel="stylesheet" />
<script src="_content/Astrol.Component.Board/js/interact.min.js"></script>
<script src="_content/Astrol.Component.Board/board.min.js"></script>
```

```csharp
// Program.cs: no longer needed (it does nothing; it can be removed)
builder.Services.AddAstrolBoard();
```

## 4. Your first board

Continue with the [**AstrolBoard**](/board-component) page (data model, interaction, guides and full reference) and the [examples](/board-example) and [performance](/board-performance) test; each example has its full code to copy.


---

# Board · Performance

> AstrolBoard: interactive Blazor board from AstrolUI with boxes you drag and resize, relations with vertices, zoom, mini-map, search, context menus, undo/redo and optional guides; smooth even with hundreds of elements.

Source page: https://doc.astrolui.com/board-performance

Board with hundreds of boxes and relations. Drag, resize and scroll: everything happens in the browser and .NET is only called on release.

## Hundreds of boxes

Choose 100, 500 or 1000 boxes, each one related to the next.

```razor
@using Astrol.Component.Board
@using Astrol.Component.Basic.Form
@using Astrol.Entities.Basic.UI.Board

@* Large board: dragging, resizing and moving vertices run in the browser (no calls to .NET while you drag),
   so it stays smooth with hundreds of boxes. Only the boxes that change are rendered again. *@
<div style="margin-bottom:5px">
    <AstrolRadioGroup Value="boxCount" ValueChanged="(int count) => Load(count)" Horizontal="true" AriaLabel="Boxes">
        @foreach (var count in new[] { 100, 500, 1000 })
        {
            <AstrolRadio Value="count" Text="@($"{count} boxes")" />
        }
    </AstrolRadioGroup>
</div>
<div style="height:420px">
    <AstrolBoard TBox="string" TRelation="object" Board="board" BackgroundType="BackgroundType.Points" MinWidth="40" MinHeight="30">
        <BoxRender>
            <div style="height:100%; display:flex; align-items:center; justify-content:center; font-size:.8em; border-radius:6px; border:1px solid var(--color-gray-a); background:var(--layout-menu-bg)">
                @context.BOX_NAME
            </div>
        </BoxRender>
    </AstrolBoard>
</div>

@code {
    private int boxCount = 500;
    private Board<string, object> board = Create(500);

    // A new Board object: the component starts again (selection and history).
    private void Load(int count)
    {
        boxCount = count;
        board = Create(count);
    }

    private static Board<string, object> Create(int count)
    {
        var b = new Board<string, object>();
        for (int i = 0; i < count; i++)
        {
            b.Boxes.Add(new Box<string> { X = 20 + (i % 25) * 120, Y = 20 + (i / 25) * 100, Width = 90, Height = 60, BOX_NAME = $"#{i + 1}", Content = "" });
        }
        for (int i = 1; i < count; i++)
        {
            b.Relations.Add(new Relation<object> { BoxIdA = b.Boxes[i - 1].Id, BoxIdB = b.Boxes[i].Id });
        }
        return b;
    }
}
```


---

# AstrolChart

> AstrolChart: Blazor charts from AstrolUI based on ApexCharts. Lines, areas, bars, circular, radar, heatmaps, ranges, candlesticks and more, with C# data and the AstrolUI light/dark theme.

Source page: https://doc.astrolui.com/chart/chart-component

**AstrolChart<TItem>** is the chart container, and one or more **series** go inside it. Each series receives a list of your own objects (**Items**) and functions that say which value goes on each axis. No arrays or JSON to prepare: you work with your own classes and LINQ.

## 1. Minimal example

## 2. How data is connected

- **TItem**: the class of your data. It goes on the chart and on each series (**TItem="Sale"**).
- **Items**: the list of objects of the series. For several series from one list, filter with LINQ: **Items="sales.Where(s => s.Year == 2026)"**.
- **XValue**: what goes on the X axis (category, number or date). Objects with the same X make a single point.
- **YValue**: the Y value of each object, when there is one object per point.
- **YAggregate**: when there are several objects per point, how they are combined: **e => e.Sum(x => x.Amount)**, **Average**, **Count()**, **Max**...
- **OrderBy / OrderByDescending**: order of the points, e.g. **OrderByDescending="p => p.Y"** for a ranking.
- **Name**: series name (legend and tooltip). **Color** sets its color; **PointColor** gives a color per point.
- **ShowDataLabels**: shows the value on each point or bar.
- **Group**: in stacked bars, series with the same Group form one stack.
- **DataPointMutator**: changes each point before it is drawn (color, extra text...).
- **Dates**: set **XAxisType="XAxisType.Datetime"** on the chart and pass the date as Unix milliseconds: **XValue="e => e.Date.ToUnixTimeMilliseconds()"**.
- **Numeric axes** (scatter): **XAxisType="XAxisType.Numeric"** and a numeric XValue.
- If the list content changes (without creating another list), call **UpdateSeriesAsync()** through **@ref**; if you assign a new list, the chart updates by itself.

## 3. Series types

- **AstrolPointSeries**: one value per point (**YValue** or **YAggregate**). Its **SeriesType** chooses the drawing:
**Line**, **Area**, **Bar** (columns; horizontal with **PlotOptions.Bar.Horizontal**), **Pie**, **Donut**, **PolarArea**, **RadialBar**, **Radar**, **Scatter**, **Heatmap** and **Treemap**.
Types can be combined in one chart (columns + line).

- **AstrolRangeSeries**: bars from a start to an end (**YMinValue**, **YMaxValue**): Gantt charts and timelines.
- **AstrolRangeAreaSeries**: band between **Bottom** and **Top** (minimum and maximum).
- **AstrolCandleSeries**: candlesticks with **Open**, **High**, **Low** and **Close**.
- **AstrolBoxPlotSeries**: box plots with **Min**, **Quantile1**, **Median**, **Quantile3** and **Max**.
- **AstrolBubbleSeries**: bubbles with **YAggregate** (position) and **ZAggregate** (size).
- **AstrolGauge**: a single-percentage indicator without defining series: **Title**, **Label**, **Percentage** (0-100) and **Options**.
- All series share **Items**, **Name**, **XValue**, **Color**, **PointColor**, **ShowDataLabels**, **Stroke** (**SeriesStroke**: Color, Width, DashSpace) and **Group**.

## 4. Options (AstrolChartOptions)

The whole look is configured with **Options** (**AstrolChartOptions<TItem>**). Its properties follow the [ApexCharts options documentation](https://apexcharts.com/docs/options/) exactly, with C# names: **Chart** (stacked, zoom, toolbar, animations), **Colors**, **Stroke** (width and curve), **Fill**, **Markers**, **DataLabels**, **Legend**, **Tooltip**, **Xaxis**, **Yaxis** (several axes), **Grid**, **PlotOptions** (per type: Bar, Pie, RadialBar, Heatmap, Treemap...), **Annotations**, **Theme** and **Responsive**. Create the options once (a field), not on every render.

```csharp
private readonly AstrolChartOptions<Sale> options = new()
{
    Chart = new Chart { Stacked = true, Toolbar = new Toolbar { Show = false } },
    Colors = new List<string> { "#ffd800", "#007bff" },
    Stroke = new Stroke { Curve = Curve.Smooth, Width = 3 },
    DataLabels = new DataLabels { Enabled = true },
    Legend = new Legend { Position = LegendPosition.Bottom },
    PlotOptions = new PlotOptions { Bar = new PlotOptionsBar { Horizontal = true, BorderRadius = 4 } },
    Xaxis = new XAxis { Title = new AxisTitle { Text = "Month" } },
    Yaxis = new List<YAxis> { new YAxis { Title = new AxisTitle { Text = "Amount" } } },
    Tooltip = new Tooltip { Shared = true, Intersect = false },
};

// <AstrolChart TItem="Sale" Options="options"> ... </AstrolChart>
```

## 5. Theme, colors and performance

- Texts, axes and tooltips follow the AstrolUI light/dark mode automatically.
- Colors: **Options.Colors** (a list, one per series or slice), **Color** on each series, **PointColor** per point or an ApexCharts palette with **Options.Theme = new Theme { Palette = PaletteType.Palette3 }**.
- Size: by default it takes the container width; set the height with **Height** (e.g. **Height="@(300)"** or **Height="@("50vh")"**).
- ApexCharts is downloaded only once and only on pages with charts. With many points, aggregate the data (YAggregate or on the server) instead of sending thousands of objects.
- **FormatXAxisLabel** and **FormatYAxisLabel** (C# functions for the labels) only work in Blazor WebAssembly; in Blazor Server use **Options.Xaxis.Labels.Formatter** (a JavaScript function as text).

### Supported parameters

**AstrolChart<TItem>**:

- TItem **(T)**, data class **(required)**.
- ChildContent **(RenderFragment)**, the series. If you use **AstrolPointTooltip**, put the series inside **<ChildContent>**.
- Title **(string)**, chart title.
- Options **(AstrolChartOptions<TItem>)**, look and behavior (see section 4).
- XAxisType **(XAxisType?)**, X axis type: **Category**, **Datetime** or **Numeric**.
- Width / Height **(object)**, size (number in px or CSS text).
- AstrolPointTooltip **(RenderFragment<HoverData<TItem>>)**, tooltip with Blazor content; **context.DataPoint.Items** are the objects of the point.
- FormatXAxisLabel / FormatYAxisLabel **(Func<decimal, string>)**, axis labels with C# (WebAssembly only).
- GroupPoints **(GroupPoints)**, groups small points into one ("Other"): **MaxCount**, **MinCount**, **PercentageThreshold**, **Name**.
- Debug **(bool)**, logs the ApexCharts calls to the console.
- Data events: **OnDataPointSelection**, **OnMarkerClick**, **OnClick** (**SelectedData<TItem>**: Series, DataPoint, IsSelected, indexes), **OnDataPointEnter** / **OnDataPointLeave** (**HoverData<TItem>**), **OnLegendClicked**, **OnXAxisLabelClick**, **OnMouseMove**, **OnMouseLeave**.
- Zoom and selection events: **OnZoomed**, **OnSelection**, **OnBrushScrolled**, **OnScrolled**, **OnBeforeZoom**, **OnBeforeResetZoom**.
- Lifecycle events: **OnBeforeMount**, **OnMounted**, **OnRendered**, **OnUpdated**, **OnAnimationEnd**.
- Annotation events: **OnAnnotationLabelClick**, **OnAnnotationLabelMouseEnter/Leave**, **OnAnnotationPointClick**, **OnAnnotationPointMouseEnter/Leave**.

### Public methods

With **@ref** (**private AstrolChart<Sale>? chart;**):

- **UpdateSeriesAsync(animate)**: reads the series again (after changing the data).
- **UpdateOptionsAsync(redrawPaths, animate, updateSyncedCharts)**: applies changes in **Options**.
- **RenderAsync()**: creates the whole chart again.
- **AppendDataAsync(items)**: adds points at the end (real-time data).
- **ToggleSeriesAsync / ShowSeriesAsync / HideSeriesAsync(name)**: shows or hides a series.
- **ToggleDataPointSelectionAsync(series, point)**: selects a point from code.
- **ZoomXAsync(start, end)** and **ResetSeriesAsync(update, resetZoom)**.
- **AddPointAnnotationAsync**, **AddXAxisAnnotationAsync**, **AddYAxisAnnotationAsync**, **RemoveAnnotationAsync(id)**, **ClearAnnotationsAsync()**.
- **GetDataUriAsync(new DataUriOptions { Scale, Width })**: PNG image of the chart (data URI).
- **SetLocaleAsync(name)**: changes the chart language (defined in **Options.Chart.Locales**).

### Examples


---

# Charts · Basic charts

> Lines, areas, columns, horizontal bars, stacked and mixed charts.

Source page: https://doc.astrolui.com/chart/examples/basic

Each example is a complete component: copy its code (markup and **@code**), including the sample data, and replace it with yours.

## Lines

Two series over the same list with a smooth curve (**Stroke.Curve = Curve.Smooth**) and markers.

```razor
@using AstrolCharts

<AstrolChart TItem="MonthlySale" Title="Monthly sales" Options="options" Height="@(300)">
    <AstrolPointSeries TItem="MonthlySale"
                       Items="sales"
                       Name="Revenue"
                       SeriesType="SeriesType.Line"
                       XValue="e => e.Month"
                       YValue="e => e.Revenue" />
    <AstrolPointSeries TItem="MonthlySale"
                       Items="sales"
                       Name="Expenses"
                       SeriesType="SeriesType.Line"
                       XValue="e => e.Month"
                       YValue="e => e.Expenses" />
</AstrolChart>

@code {
    private readonly AstrolChartOptions<MonthlySale> options = new()
    {
        Stroke = new Stroke { Curve = Curve.Smooth, Width = 3 },
        Markers = new Markers { Size = 4 },
    };

    private readonly List<MonthlySale> sales = new()
    {
        new() { Month = "Jan", Revenue = 420, Expenses = 310 },
        new() { Month = "Feb", Revenue = 380, Expenses = 290 },
        new() { Month = "Mar", Revenue = 510, Expenses = 330 },
        new() { Month = "Apr", Revenue = 470, Expenses = 360 },
        new() { Month = "May", Revenue = 620, Expenses = 400 },
        new() { Month = "Jun", Revenue = 580, Expenses = 380 },
    };

    public class MonthlySale
    {
        public string Month { get; set; } = string.Empty;
        public decimal Revenue { get; set; }
        public decimal Expenses { get; set; }
    }
}
```

## Areas

**SeriesType.Area** with gradient fill (**Fill**) and no data labels.

```razor
@using AstrolCharts

<AstrolChart TItem="Visit" Title="Website visits" Options="options" Height="@(300)">
    <AstrolPointSeries TItem="Visit"
                       Items="visits"
                       Name="Desktop"
                       SeriesType="SeriesType.Area"
                       XValue="e => e.Day"
                       YValue="e => e.Desktop" />
    <AstrolPointSeries TItem="Visit"
                       Items="visits"
                       Name="Mobile"
                       SeriesType="SeriesType.Area"
                       XValue="e => e.Day"
                       YValue="e => e.Mobile" />
</AstrolChart>

@code {
    private readonly AstrolChartOptions<Visit> options = new()
    {
        Stroke = new Stroke { Curve = Curve.Smooth, Width = 2 },
        Fill = new Fill { Type = FillType.Gradient, Opacity = 0.4 },
        DataLabels = new DataLabels { Enabled = false },
    };

    private readonly List<Visit> visits = new()
    {
        new() { Day = "Mon", Desktop = 120, Mobile = 210 },
        new() { Day = "Tue", Desktop = 150, Mobile = 260 },
        new() { Day = "Wed", Desktop = 180, Mobile = 240 },
        new() { Day = "Thu", Desktop = 140, Mobile = 300 },
        new() { Day = "Fri", Desktop = 200, Mobile = 350 },
        new() { Day = "Sat", Desktop = 90, Mobile = 410 },
        new() { Day = "Sun", Desktop = 70, Mobile = 380 },
    };

    public class Visit
    {
        public string Day { get; set; } = string.Empty;
        public decimal Desktop { get; set; }
        public decimal Mobile { get; set; }
    }
}
```

## Columns with aggregation

Several orders per country: **YAggregate** adds them up per X and **OrderByDescending** sorts from highest to lowest. **ShowDataLabels** shows the value.

```razor
@using AstrolCharts

@* Several orders per country: YAggregate groups them by XValue (here, the sum). *@
<AstrolChart TItem="Order" Title="Sales by country" Options="options" Height="@(300)">
    <AstrolPointSeries TItem="Order"
                       Items="orders"
                       Name="Gross"
                       SeriesType="SeriesType.Bar"
                       ShowDataLabels="true"
                       XValue="e => e.Country"
                       YAggregate="e => e.Sum(o => o.Gross)"
                       OrderByDescending="p => p.Y" />
    <AstrolPointSeries TItem="Order"
                       Items="orders"
                       Name="Net"
                       SeriesType="SeriesType.Bar"
                       XValue="e => e.Country"
                       YAggregate="e => e.Sum(o => o.Net)"
                       OrderByDescending="p => p.Y" />
</AstrolChart>

@code {
    private readonly AstrolChartOptions<Order> options = new()
    {
        PlotOptions = new PlotOptions { Bar = new PlotOptionsBar { BorderRadius = 4, ColumnWidth = "60%" } },
    };

    private readonly List<Order> orders = new()
    {
        new() { Country = "Spain", Gross = 120, Net = 100 },
        new() { Country = "Spain", Gross = 80, Net = 70 },
        new() { Country = "Mexico", Gross = 150, Net = 125 },
        new() { Country = "Mexico", Gross = 95, Net = 80 },
        new() { Country = "Peru", Gross = 110, Net = 92 },
        new() { Country = "Chile", Gross = 75, Net = 60 },
        new() { Country = "Chile", Gross = 40, Net = 35 },
    };

    public class Order
    {
        public string Country { get; set; } = string.Empty;
        public decimal Gross { get; set; }
        public decimal Net { get; set; }
    }
}
```

## Horizontal bars

**PlotOptions.Bar.Horizontal = true**; with **Distributed = true** each bar gets its own color.

```razor
@using AstrolCharts

<AstrolChart TItem="Language" Title="Most used languages" Options="options" Height="@(300)">
    <AstrolPointSeries TItem="Language"
                       Items="languages"
                       Name="Developers (%)"
                       SeriesType="SeriesType.Bar"
                       ShowDataLabels="true"
                       XValue="e => e.Name"
                       YValue="e => e.Percentage"
                       OrderByDescending="p => p.Y" />
</AstrolChart>

@code {
    private readonly AstrolChartOptions<Language> options = new()
    {
        // Horizontal bars, one color per bar
        PlotOptions = new PlotOptions { Bar = new PlotOptionsBar { Horizontal = true, Distributed = true, BorderRadius = 4 } },
        Legend = new Legend { Show = false },
    };

    private readonly List<Language> languages = new()
    {
        new() { Name = "JavaScript", Percentage = 62 },
        new() { Name = "Python", Percentage = 51 },
        new() { Name = "C#", Percentage = 27 },
        new() { Name = "Java", Percentage = 30 },
        new() { Name = "Go", Percentage = 13 },
    };

    public class Language
    {
        public string Name { get; set; } = string.Empty;
        public decimal Percentage { get; set; }
    }
}
```

## Stacked columns

**Chart.Stacked = true** stacks the series. With **StackType = StackType.Percent100** they are shown as percentages.

```razor
@using AstrolCharts

<AstrolChart TItem="Quarter" Title="Sales by channel" Options="options" Height="@(300)">
    <AstrolPointSeries TItem="Quarter"
                       Items="quarters"
                       Name="Store"
                       SeriesType="SeriesType.Bar"
                       XValue="e => e.Name"
                       YValue="e => e.Store" />
    <AstrolPointSeries TItem="Quarter"
                       Items="quarters"
                       Name="Online"
                       SeriesType="SeriesType.Bar"
                       XValue="e => e.Name"
                       YValue="e => e.Online" />
    <AstrolPointSeries TItem="Quarter"
                       Items="quarters"
                       Name="Wholesale"
                       SeriesType="SeriesType.Bar"
                       XValue="e => e.Name"
                       YValue="e => e.Wholesale" />
</AstrolChart>

@code {
    private readonly AstrolChartOptions<Quarter> options = new()
    {
        // Stacked = true piles the series; StackType = StackType.Percent100 shows percentages
        Chart = new Chart { Stacked = true },
        PlotOptions = new PlotOptions { Bar = new PlotOptionsBar { ColumnWidth = "50%" } },
    };

    private readonly List<Quarter> quarters = new()
    {
        new() { Name = "Q1", Store = 44, Online = 53, Wholesale = 12 },
        new() { Name = "Q2", Store = 55, Online = 32, Wholesale = 17 },
        new() { Name = "Q3", Store = 41, Online = 33, Wholesale = 11 },
        new() { Name = "Q4", Store = 67, Online = 52, Wholesale = 9 },
    };

    public class Quarter
    {
        public string Name { get; set; } = string.Empty;
        public decimal Store { get; set; }
        public decimal Online { get; set; }
        public decimal Wholesale { get; set; }
    }
}
```

## Mixed (columns and line)

Each series chooses its **SeriesType**. Two Y axes in **Options.Yaxis**: the second one with **Opposite = true**.

```razor
@using AstrolCharts

@* Each series chooses its own type: columns for units and a line for the average price. *@
<AstrolChart TItem="ProductSale" Title="Units and average price" Options="options" Height="@(300)">
    <AstrolPointSeries TItem="ProductSale"
                       Items="sales"
                       Name="Units"
                       SeriesType="SeriesType.Bar"
                       XValue="e => e.Month"
                       YValue="e => e.Units" />
    <AstrolPointSeries TItem="ProductSale"
                       Items="sales"
                       Name="Average price"
                       SeriesType="SeriesType.Line"
                       XValue="e => e.Month"
                       YValue="e => e.AveragePrice" />
</AstrolChart>

@code {
    private readonly AstrolChartOptions<ProductSale> options = new()
    {
        Stroke = new Stroke { Width = new List<double> { 0, 4 } }, // no border on bars, 4px line
        // Two Y axes: the second one (Opposite) for the price
        Yaxis = new List<YAxis>
        {
            new YAxis { Title = new AxisTitle { Text = "Units" } },
            new YAxis { Opposite = true, Title = new AxisTitle { Text = "Price" } },
        },
    };

    private readonly List<ProductSale> sales = new()
    {
        new() { Month = "Jan", Units = 230, AveragePrice = 21 },
        new() { Month = "Feb", Units = 310, AveragePrice = 19 },
        new() { Month = "Mar", Units = 280, AveragePrice = 22 },
        new() { Month = "Apr", Units = 420, AveragePrice = 18 },
        new() { Month = "May", Units = 390, AveragePrice = 20 },
        new() { Month = "Jun", Units = 470, AveragePrice = 17 },
    };

    public class ProductSale
    {
        public string Month { get; set; } = string.Empty;
        public decimal Units { get; set; }
        public decimal AveragePrice { get; set; }
    }
}
```


---

# Charts · Circular charts

> Pie, donut, polar area, radial bars and gauge.

Source page: https://doc.astrolui.com/chart/examples/circular

Each example is a complete component: copy its code (markup and **@code**), including the sample data, and replace it with yours.

## Pie

**SeriesType.Pie**: XValue is the name of each slice and YValue its value (they do not need to add up to 100).

```razor
@using AstrolCharts

<AstrolChart TItem="Share" Title="Market share" Height="@(320)">
    <AstrolPointSeries TItem="Share"
                       Items="shares"
                       Name="Share"
                       SeriesType="SeriesType.Pie"
                       XValue="e => e.Browser"
                       YValue="e => e.Percentage" />
</AstrolChart>

@code {
    private readonly List<Share> shares = new()
    {
        new() { Browser = "Chrome", Percentage = 64 },
        new() { Browser = "Safari", Percentage = 19 },
        new() { Browser = "Edge", Percentage = 5 },
        new() { Browser = "Firefox", Percentage = 3 },
        new() { Browser = "Others", Percentage = 9 },
    };

    public class Share
    {
        public string Browser { get; set; } = string.Empty;
        public decimal Percentage { get; set; }
    }
}
```

## Donut

**SeriesType.Donut** with custom colors (**Options.Colors**) and the legend at the bottom.

```razor
@using AstrolCharts

<AstrolChart TItem="Expense" Title="Monthly budget" Options="options" Height="@(320)">
    <AstrolPointSeries TItem="Expense"
                       Items="expenses"
                       Name="Amount"
                       SeriesType="SeriesType.Donut"
                       XValue="e => e.Category"
                       YValue="e => e.Amount" />
</AstrolChart>

@code {
    private readonly AstrolChartOptions<Expense> options = new()
    {
        Legend = new Legend { Position = LegendPosition.Bottom },
        // A custom color per slice (in the same order as the data)
        Colors = new List<string> { "#ffd800", "#007bff", "#12ba38", "#ff6a00", "#b200ff" },
    };

    private readonly List<Expense> expenses = new()
    {
        new() { Category = "Rent", Amount = 900 },
        new() { Category = "Food", Amount = 450 },
        new() { Category = "Transport", Amount = 180 },
        new() { Category = "Leisure", Amount = 220 },
        new() { Category = "Savings", Amount = 300 },
    };

    public class Expense
    {
        public string Category { get; set; } = string.Empty;
        public decimal Amount { get; set; }
    }
}
```

## Polar area

**SeriesType.PolarArea**: the radius of each sector depends on its value.

```razor
@using AstrolCharts

<AstrolChart TItem="Rating" Title="Customer rating" Options="options" Height="@(320)">
    <AstrolPointSeries TItem="Rating"
                       Items="ratings"
                       Name="Score"
                       SeriesType="SeriesType.PolarArea"
                       XValue="e => e.Aspect"
                       YValue="e => e.Score" />
</AstrolChart>

@code {
    private readonly AstrolChartOptions<Rating> options = new()
    {
        Fill = new Fill { Opacity = 0.85 },
        Legend = new Legend { Position = LegendPosition.Bottom },
    };

    private readonly List<Rating> ratings = new()
    {
        new() { Aspect = "Price", Score = 7 },
        new() { Aspect = "Quality", Score = 9 },
        new() { Aspect = "Support", Score = 8 },
        new() { Aspect = "Delivery", Score = 6 },
        new() { Aspect = "Design", Score = 9 },
    };

    public class Rating
    {
        public string Aspect { get; set; } = string.Empty;
        public decimal Score { get; set; }
    }
}
```

## Radial bars

**SeriesType.RadialBar** with values from 0 to 100 and the average in the center (**PlotOptions.RadialBar.DataLabels.Total**).

```razor
@using AstrolCharts

@* Values are percentages (0-100). *@
<AstrolChart TItem="Goal" Title="Annual goals" Options="options" Height="@(330)">
    <AstrolPointSeries TItem="Goal"
                       Items="goals"
                       Name="Progress"
                       SeriesType="SeriesType.RadialBar"
                       XValue="e => e.Name"
                       YValue="e => e.Percentage" />
</AstrolChart>

@code {
    private readonly AstrolChartOptions<Goal> options = new()
    {
        PlotOptions = new PlotOptions
        {
            RadialBar = new PlotOptionsRadialBar
            {
                Hollow = new Hollow { Size = "35%" },
                DataLabels = new RadialBarDataLabels
                {
                    Total = new RadialBarDataLabelsTotal { Show = true, Label = "Average" },
                },
            },
        },
    };

    private readonly List<Goal> goals = new()
    {
        new() { Name = "Sales", Percentage = 82 },
        new() { Name = "Customers", Percentage = 64 },
        new() { Name = "Courses", Percentage = 45 },
    };

    public class Goal
    {
        public string Name { get; set; } = string.Empty;
        public decimal Percentage { get; set; }
    }
}
```

## Gauge (AstrolGauge)

**AstrolGauge** shows a single percentage without defining series. It updates when **Percentage** changes.

```razor
@using AstrolCharts
@using Astrol.Component.Basic.Button
@using Astrol.Entities.Basic.UI

@* AstrolGauge: a single percentage without defining series. *@
<AstrolGauge Title="Disk usage" Label="Used" Percentage="percentage" />

<div style="text-align:center">
    <AstrolButton Icon="astrol-minus-1" Style="AstrolStyle.Blue" Title="-10" OnClick="() => Change(-10)" />
    <AstrolButton Icon="astrol-plus-1" Style="AstrolStyle.Blue" Title="+10" OnClick="() => Change(10)" />
</div>

@code {
    private decimal percentage = 68;

    private void Change(decimal delta) => percentage = Math.Clamp(percentage + delta, 0, 100);
}
```


---

# Charts · Interaction

> Dates with zoom, annotations, events and changing data, custom tooltip and export to image.

Source page: https://doc.astrolui.com/chart/examples/interaction

Each example is a complete component: copy its code (markup and **@code**), including the sample data, and replace it with yours.

## Dates and zoom

Date axis (**XAxisType.Datetime**) with zoom: drag over the chart to zoom in; the toolbar resets it.

```razor
@using AstrolCharts

@* Date axis: X goes as Unix milliseconds. Drag over the chart to zoom; the toolbar resets it. *@
<AstrolChart TItem="DailyValue" Title="Daily orders" XAxisType="XAxisType.Datetime" Options="options" Height="@(320)">
    <AstrolPointSeries TItem="DailyValue"
                       Items="values"
                       Name="Orders"
                       SeriesType="SeriesType.Area"
                       XValue="e => e.Date.ToUnixTimeMilliseconds()"
                       YValue="e => e.Orders" />
</AstrolChart>

@code {
    private readonly AstrolChartOptions<DailyValue> options = new()
    {
        Chart = new Chart
        {
            Zoom = new Zoom { Enabled = true, Type = AxisType.X, AutoScaleYaxis = true },
            Toolbar = new Toolbar { Show = true },
        },
        Xaxis = new XAxis { Labels = new XAxisLabels { Format = "dd MMM" } },
        DataLabels = new DataLabels { Enabled = false },
        Stroke = new Stroke { Width = 2 },
    };

    // Deterministic sample: 90 days
    private readonly List<DailyValue> values = Enumerable.Range(0, 90)
        .Select(i => new DailyValue
        {
            Date = new DateTimeOffset(2026, 1, 1, 0, 0, 0, TimeSpan.Zero).AddDays(i),
            Orders = 40 + (i * 7 % 23) + i / 3,
        })
        .ToList();

    public class DailyValue
    {
        public DateTimeOffset Date { get; set; }
        public decimal Orders { get; set; }
    }
}
```

## Annotations

**Options.Annotations**: a horizontal line (goal) and a vertical band (campaign). They can also be added from code.

```razor
@using AstrolCharts

@* Annotations: a horizontal line (goal) and a vertical band (campaign). *@
<AstrolChart TItem="WeeklySale" Title="Weekly sales" Options="options" Height="@(320)">
    <AstrolPointSeries TItem="WeeklySale"
                       Items="sales"
                       Name="Sales"
                       SeriesType="SeriesType.Line"
                       XValue="e => e.Week"
                       YValue="e => e.Amount" />
</AstrolChart>

@code {
    private readonly AstrolChartOptions<WeeklySale> options = new()
    {
        Stroke = new Stroke { Width = 3 },
        Annotations = new Annotations
        {
            Yaxis = new List<AnnotationsYAxis>
            {
                new AnnotationsYAxis
                {
                    Y = 500,
                    BorderColor = "#12ba38",
                    Label = new Label { Text = "Goal", Style = new Style { Background = "#12ba38", Color = "#fff" } },
                },
            },
            Xaxis = new List<AnnotationsXAxis>
            {
                new AnnotationsXAxis
                {
                    X = "W4",
                    X2 = "W6",
                    FillColor = "#ffd800",
                    Opacity = 0.2,
                    Label = new Label { Text = "Campaign", Style = new Style { Background = "#ffd800", Color = "#222" } },
                },
            },
        },
    };

    private readonly List<WeeklySale> sales = new()
    {
        new() { Week = "W1", Amount = 320 },
        new() { Week = "W2", Amount = 360 },
        new() { Week = "W3", Amount = 340 },
        new() { Week = "W4", Amount = 450 },
        new() { Week = "W5", Amount = 560 },
        new() { Week = "W6", Amount = 610 },
        new() { Week = "W7", Amount = 480 },
        new() { Week = "W8", Amount = 470 },
    };

    public class WeeklySale
    {
        public string Week { get; set; } = string.Empty;
        public decimal Amount { get; set; }
    }
}
```

## Events and changing data

Click a column (**OnDataPointSelection**), generate new data (**UpdateSeriesAsync**) or hide a series (**ToggleSeriesAsync**).

```razor
@using AstrolCharts
@using Astrol.Component.Basic.Button
@using Astrol.Entities.Basic.UI

@* Click a column (OnDataPointSelection), change the data (UpdateSeriesAsync) or hide a series (ToggleSeriesAsync). *@
<AstrolChart @ref="chart"
             TItem="TeamResult"
             Title="Results by team"
             Height="@(300)"
             OnDataPointSelection="OnSelected">
    <AstrolPointSeries TItem="TeamResult"
                       Items="results"
                       Name="Won"
                       SeriesType="SeriesType.Bar"
                       XValue="e => e.Team"
                       YValue="e => e.Won" />
    <AstrolPointSeries TItem="TeamResult"
                       Items="results"
                       Name="Lost"
                       SeriesType="SeriesType.Bar"
                       XValue="e => e.Team"
                       YValue="e => e.Lost" />
</AstrolChart>

<div style="padding:5px 10px">
    <AstrolButton Icon="astrol-arrows-cw" Text="New data" Style="AstrolStyle.Blue" OnClick="NewData" />
    <AstrolButton Icon="astrol-eye" Text="Show / hide Lost" Style="AstrolStyle.White" OnClick="ToggleLost" />
    <p aria-live="polite">@message</p>
</div>

@code {
    private AstrolChart<TeamResult>? chart;
    private string message = "Click a column.";
    private int round;

    private readonly List<TeamResult> results = new()
    {
        new() { Team = "Lions", Won = 12, Lost = 4 },
        new() { Team = "Eagles", Won = 9, Lost = 7 },
        new() { Team = "Sharks", Won = 14, Lost = 2 },
        new() { Team = "Wolves", Won = 6, Lost = 10 },
    };

    private void OnSelected(SelectedData<TeamResult> selected)
    {
        var team = selected.DataPoint.Items.First();
        message = selected.IsSelected
            ? $"{selected.Series.Name} - {team.Team}: won {team.Won}, lost {team.Lost}"
            : "Selection cleared.";
    }

    private async Task NewData()
    {
        round++;
        foreach (var (team, i) in results.Select((t, i) => (t, i)))
        {
            team.Won = (round * 5 + i * 3) % 15 + 2;
            team.Lost = (round * 3 + i * 7) % 12 + 1;
        }

        // The list is the same object: tell the chart to read it again
        await chart!.UpdateSeriesAsync(animate: true);
    }

    private Task ToggleLost() => chart!.ToggleSeriesAsync("Lost");

    public class TeamResult
    {
        public string Team { get; set; } = string.Empty;
        public decimal Won { get; set; }
        public decimal Lost { get; set; }
    }
}
```

## Custom tooltip

**AstrolPointTooltip** renders the tooltip with Blazor; **context.DataPoint.Items** holds the objects of the point. The series go in **<ChildContent>**.

```razor
@using AstrolCharts

@* AstrolPointTooltip: Blazor content of the tooltip. context.DataPoint.Items are the items of the point.
   With a tooltip, the series go inside <ChildContent>. *@
<AstrolChart TItem="Product" Title="Top products" Height="@(300)">
    <ChildContent>
        <AstrolPointSeries TItem="Product"
                           Items="products"
                           Name="Units sold"
                           SeriesType="SeriesType.Bar"
                           XValue="e => e.Name"
                           YValue="e => e.Units" />
    </ChildContent>
    <AstrolPointTooltip>
        @{ var product = context.DataPoint.Items.First(); }
        <div style="padding:10px; min-width:160px">
            <b>@product.Name</b>
            <div>Units: @product.Units</div>
            <div>Price: @product.Price.ToString("C")</div>
            <div>Revenue: <b>@((product.Units * product.Price).ToString("C"))</b></div>
        </div>
    </AstrolPointTooltip>
</AstrolChart>

@code {
    private readonly List<Product> products = new()
    {
        new() { Name = "Keyboard", Units = 320, Price = 35 },
        new() { Name = "Mouse", Units = 540, Price = 18 },
        new() { Name = "Monitor", Units = 120, Price = 210 },
        new() { Name = "Headset", Units = 260, Price = 49 },
    };

    public class Product
    {
        public string Name { get; set; } = string.Empty;
        public decimal Units { get; set; }
        public decimal Price { get; set; }
    }
}
```

## Export to image

**GetDataUriAsync** returns the chart as a PNG (data URI) to show it, save it or include it in a report.

```razor
@using AstrolCharts
@using Astrol.Component.Basic.Button
@using Astrol.Entities.Basic.UI

@* GetDataUriAsync returns the chart as a PNG (data URI) to show it, save it or put it in a report. *@
<AstrolChart @ref="chart" TItem="Channel" Title="Leads by channel" Height="@(260)">
    <AstrolPointSeries TItem="Channel"
                       Items="channels"
                       Name="Leads"
                       SeriesType="SeriesType.Donut"
                       XValue="e => e.Name"
                       YValue="e => e.Leads" />
</AstrolChart>

<div style="padding:5px 10px">
    <AstrolButton Icon="astrol-picture" Text="Get image" Style="AstrolStyle.Blue" OnClick="Export" />
    @if (image != null)
    {
        <img src="@image" alt="Exported chart" style="max-width:100%; border:1px solid var(--color-gray-a); margin-top:5px" />
    }
</div>

@code {
    private AstrolChart<Channel>? chart;
    private string? image;

    private async Task Export()
    {
        image = await chart!.GetDataUriAsync(new DataUriOptions { Scale = 1 });
    }

    private readonly List<Channel> channels = new()
    {
        new() { Name = "Search", Leads = 420 },
        new() { Name = "Social", Leads = 310 },
        new() { Name = "Email", Leads = 180 },
        new() { Name = "Referral", Leads = 95 },
    };

    public class Channel
    {
        public string Name { get; set; } = string.Empty;
        public decimal Leads { get; set; }
    }
}
```


---

# Charts · Other types

> Radar, scatter, bubbles, heatmap and treemap.

Source page: https://doc.astrolui.com/chart/examples/more

Each example is a complete component: copy its code (markup and **@code**), including the sample data, and replace it with yours.

## Radar

One series per person, created with **@foreach** by filtering the same list.

```razor
@using AstrolCharts

@* One series per person: each one filters the same list. *@
<AstrolChart TItem="SkillScore" Title="Team skills" Height="@(340)">
    @foreach (var person in scores.Select(s => s.Person).Distinct())
    {
        <AstrolPointSeries TItem="SkillScore"
                           Items="scores.Where(s => s.Person == person)"
                           Name="@person"
                           SeriesType="SeriesType.Radar"
                           XValue="e => e.Skill"
                           YValue="e => e.Score" />
    }
</AstrolChart>

@code {
    private readonly List<SkillScore> scores = new()
    {
        new() { Person = "Ana", Skill = "C#", Score = 9 },
        new() { Person = "Ana", Skill = "SQL", Score = 7 },
        new() { Person = "Ana", Skill = "CSS", Score = 5 },
        new() { Person = "Ana", Skill = "Testing", Score = 8 },
        new() { Person = "Ana", Skill = "Design", Score = 4 },
        new() { Person = "Luis", Skill = "C#", Score = 6 },
        new() { Person = "Luis", Skill = "SQL", Score = 9 },
        new() { Person = "Luis", Skill = "CSS", Score = 8 },
        new() { Person = "Luis", Skill = "Testing", Score = 5 },
        new() { Person = "Luis", Skill = "Design", Score = 7 },
    };

    public class SkillScore
    {
        public string Person { get; set; } = string.Empty;
        public string Skill { get; set; } = string.Empty;
        public decimal Score { get; set; }
    }
}
```

## Scatter

**XAxisType.Numeric**: each object is an (x, y) point. One series per group.

```razor
@using AstrolCharts

@* Numeric X axis: each point is an (x, y) pair. *@
<AstrolChart TItem="Measure" Title="Height vs. weight" XAxisType="XAxisType.Numeric" Options="options" Height="@(320)">
    @foreach (var group in measures.Select(m => m.Group).Distinct())
    {
        <AstrolPointSeries TItem="Measure"
                           Items="measures.Where(m => m.Group == group)"
                           Name="@group"
                           SeriesType="SeriesType.Scatter"
                           XValue="e => e.Height"
                           YValue="e => e.Weight" />
    }
</AstrolChart>

@code {
    private readonly AstrolChartOptions<Measure> options = new()
    {
        Xaxis = new XAxis { Title = new AxisTitle { Text = "Height (cm)" }, TickAmount = 6 },
        Yaxis = new List<YAxis> { new YAxis { Title = new AxisTitle { Text = "Weight (kg)" } } },
        Markers = new Markers { Size = 7 },
    };

    private readonly List<Measure> measures = new()
    {
        new() { Group = "Women", Height = 158, Weight = 52 },
        new() { Group = "Women", Height = 162, Weight = 57 },
        new() { Group = "Women", Height = 167, Weight = 60 },
        new() { Group = "Women", Height = 171, Weight = 63 },
        new() { Group = "Women", Height = 164, Weight = 66 },
        new() { Group = "Men", Height = 170, Weight = 68 },
        new() { Group = "Men", Height = 176, Weight = 74 },
        new() { Group = "Men", Height = 181, Weight = 80 },
        new() { Group = "Men", Height = 186, Weight = 85 },
        new() { Group = "Men", Height = 174, Weight = 79 },
    };

    public class Measure
    {
        public string Group { get; set; } = string.Empty;
        public decimal Height { get; set; }
        public decimal Weight { get; set; }
    }
}
```

## Bubbles

**AstrolBubbleSeries**: **YAggregate** gives the height (average price) and **ZAggregate** the size (count).

```razor
@using AstrolCharts

@* X = city, Y = average price, Z (bubble size) = number of sales. *@
<AstrolChart TItem="HouseSale" Title="Housing market" Options="options" Height="@(320)">
    <AstrolBubbleSeries TItem="HouseSale"
                        Items="sales"
                        Name="Sales"
                        XValue="e => e.City"
                        YAggregate="e => e.Average(s => s.Price)"
                        ZAggregate="e => e.Count()" />
</AstrolChart>

@code {
    private readonly AstrolChartOptions<HouseSale> options = new()
    {
        Yaxis = new List<YAxis> { new YAxis { Title = new AxisTitle { Text = "Average price (k)" } } },
        Fill = new Fill { Opacity = 0.7 },
    };

    private readonly List<HouseSale> sales = new()
    {
        new() { City = "Lima", Price = 120 },
        new() { City = "Lima", Price = 140 },
        new() { City = "Lima", Price = 110 },
        new() { City = "Bogota", Price = 95 },
        new() { City = "Bogota", Price = 105 },
        new() { City = "Madrid", Price = 310 },
        new() { City = "Madrid", Price = 280 },
        new() { City = "Madrid", Price = 330 },
        new() { City = "Madrid", Price = 300 },
        new() { City = "Quito", Price = 85 },
    };

    public class HouseSale
    {
        public string City { get; set; } = string.Empty;
        public decimal Price { get; set; }
    }
}
```

## Heatmap

**SeriesType.Heatmap**: each series is a row (day) and X the column (hour); the color shows the value.

```razor
@using AstrolCharts

@* One series (row) per day; X = hour. The color shows the value. *@
<AstrolChart TItem="Activity" Title="Activity by day and hour" Options="options" Height="@(320)">
    @foreach (var day in days)
    {
        <AstrolPointSeries TItem="Activity"
                           Items="activity.Where(a => a.Day == day)"
                           Name="@day"
                           SeriesType="SeriesType.Heatmap"
                           XValue="e => e.Hour"
                           YValue="e => e.Count" />
    }
</AstrolChart>

@code {
    private static readonly string[] days = { "Mon", "Tue", "Wed", "Thu", "Fri" };
    private static readonly string[] hours = { "08h", "10h", "12h", "14h", "16h", "18h" };

    private readonly AstrolChartOptions<Activity> options = new()
    {
        Colors = new List<string> { "#007bff" },
        DataLabels = new DataLabels { Enabled = true },
    };

    // Deterministic sample data
    private readonly List<Activity> activity = days
        .SelectMany((day, d) => hours.Select((hour, h) => new Activity { Day = day, Hour = hour, Count = (d * 7 + h * 13) % 40 + 5 }))
        .ToList();

    public class Activity
    {
        public string Day { get; set; } = string.Empty;
        public string Hour { get; set; } = string.Empty;
        public decimal Count { get; set; }
    }
}
```

## Treemap

**SeriesType.Treemap**: each rectangle's area is proportional to its value.

```razor
@using AstrolCharts

@* Each rectangle's area is proportional to its value. *@
<AstrolChart TItem="Folder" Title="Disk usage by folder" Options="options" Height="@(320)">
    <AstrolPointSeries TItem="Folder"
                       Items="folders"
                       Name="GB"
                       SeriesType="SeriesType.Treemap"
                       XValue="e => e.Name"
                       YValue="e => e.SizeGb" />
</AstrolChart>

@code {
    private readonly AstrolChartOptions<Folder> options = new()
    {
        PlotOptions = new PlotOptions { Treemap = new PlotOptionsTreemap { Distributed = true, EnableShades = false } },
        Legend = new Legend { Show = false },
    };

    private readonly List<Folder> folders = new()
    {
        new() { Name = "Videos", SizeGb = 210 },
        new() { Name = "Photos", SizeGb = 120 },
        new() { Name = "Projects", SizeGb = 95 },
        new() { Name = "Music", SizeGb = 48 },
        new() { Name = "Documents", SizeGb = 22 },
        new() { Name = "Downloads", SizeGb = 64 },
        new() { Name = "Backups", SizeGb = 150 },
    };

    public class Folder
    {
        public string Name { get; set; } = string.Empty;
        public decimal SizeGb { get; set; }
    }
}
```


---

# Charts · Ranges and finance

> Timeline (Gantt), range area, candlesticks and box plot.

Source page: https://doc.astrolui.com/chart/examples/ranges

Each example is a complete component: copy its code (markup and **@code**), including the sample data, and replace it with yours.

## Timeline (Gantt)

**AstrolRangeSeries** with **YMinValue** / **YMaxValue** in Unix milliseconds, horizontal bars and **XAxisType.Datetime**.

```razor
@using AstrolCharts

@* Timeline (Gantt): a bar from YMinValue to YMaxValue per task. Dates go as Unix milliseconds. *@
<AstrolChart TItem="ProjectTask" Title="Project plan" XAxisType="XAxisType.Datetime" Options="options" Height="@(320)">
    <AstrolRangeSeries TItem="ProjectTask"
                       Items="tasks"
                       Name="Tasks"
                       XValue="e => e.Name"
                       YMinValue="e => e.Start.ToUnixTimeMilliseconds()"
                       YMaxValue="e => e.End.ToUnixTimeMilliseconds()" />
</AstrolChart>

@code {
    private readonly AstrolChartOptions<ProjectTask> options = new()
    {
        PlotOptions = new PlotOptions { Bar = new PlotOptionsBar { Horizontal = true, Distributed = true, BorderRadius = 4 } },
        Legend = new Legend { Show = false },
    };

    private static readonly DateTimeOffset start = new(2026, 1, 5, 0, 0, 0, TimeSpan.Zero);

    private readonly List<ProjectTask> tasks = new()
    {
        new() { Name = "Analysis", Start = start, End = start.AddDays(10) },
        new() { Name = "Design", Start = start.AddDays(7), End = start.AddDays(21) },
        new() { Name = "Development", Start = start.AddDays(18), End = start.AddDays(50) },
        new() { Name = "Testing", Start = start.AddDays(45), End = start.AddDays(60) },
        new() { Name = "Release", Start = start.AddDays(60), End = start.AddDays(63) },
    };

    public class ProjectTask
    {
        public string Name { get; set; } = string.Empty;
        public DateTimeOffset Start { get; set; }
        public DateTimeOffset End { get; set; }
    }
}
```

## Range area

**AstrolRangeAreaSeries** (band between **Bottom** and **Top**) combined with a line.

```razor
@using AstrolCharts

@* Band between the minimum (Bottom) and maximum (Top) temperature, with the average as a line. *@
<AstrolChart TItem="Temperature" Title="Temperature range" Options="options" Height="@(320)">
    <AstrolRangeAreaSeries TItem="Temperature"
                           Items="temperatures"
                           Name="Min - Max"
                           XValue="e => e.Month"
                           Bottom="e => e.Min"
                           Top="e => e.Max" />
    <AstrolPointSeries TItem="Temperature"
                       Items="temperatures"
                       Name="Average"
                       SeriesType="SeriesType.Line"
                       XValue="e => e.Month"
                       YValue="e => e.Average" />
</AstrolChart>

@code {
    private readonly AstrolChartOptions<Temperature> options = new()
    {
        Stroke = new Stroke { Curve = Curve.Smooth, Width = new List<double> { 0, 3 } },
        Fill = new Fill { Opacity = new List<double> { 0.25, 1 } },
        Yaxis = new List<YAxis> { new YAxis { Title = new AxisTitle { Text = "°C" } } },
    };

    private readonly List<Temperature> temperatures = new()
    {
        new() { Month = "Jan", Min = 2, Max = 11, Average = 6 },
        new() { Month = "Feb", Min = 3, Max = 13, Average = 8 },
        new() { Month = "Mar", Min = 6, Max = 17, Average = 11 },
        new() { Month = "Apr", Min = 8, Max = 20, Average = 14 },
        new() { Month = "May", Min = 12, Max = 25, Average = 18 },
        new() { Month = "Jun", Min = 16, Max = 30, Average = 23 },
    };

    public class Temperature
    {
        public string Month { get; set; } = string.Empty;
        public decimal Min { get; set; }
        public decimal Max { get; set; }
        public decimal Average { get; set; }
    }
}
```

## Candlesticks

**AstrolCandleSeries** with **Open**, **High**, **Low** and **Close** per date.

```razor
@using AstrolCharts

@* Open, high, low and close per day. Green = closed up, red = closed down. *@
<AstrolChart TItem="StockDay" Title="ACME stock" XAxisType="XAxisType.Datetime" Height="@(320)">
    <AstrolCandleSeries TItem="StockDay"
                        Items="prices"
                        Name="ACME"
                        XValue="e => e.Date.ToUnixTimeMilliseconds()"
                        Open="e => e.Open"
                        High="e => e.High"
                        Low="e => e.Low"
                        Close="e => e.Close" />
</AstrolChart>

@code {
    private readonly List<StockDay> prices = Generate();

    // Deterministic sample: 20 trading days
    private static List<StockDay> Generate()
    {
        var list = new List<StockDay>();
        var date = new DateTimeOffset(2026, 3, 2, 0, 0, 0, TimeSpan.Zero);
        decimal close = 100;
        for (int i = 0; i < 20; i++)
        {
            var open = close;
            close = open + ((i * 37) % 11 - 5);
            list.Add(new StockDay
            {
                Date = date.AddDays(i),
                Open = open,
                Close = close,
                High = Math.Max(open, close) + (i % 3) + 1,
                Low = Math.Min(open, close) - (i % 4) - 1,
            });
        }
        return list;
    }

    public class StockDay
    {
        public DateTimeOffset Date { get; set; }
        public decimal Open { get; set; }
        public decimal High { get; set; }
        public decimal Low { get; set; }
        public decimal Close { get; set; }
    }
}
```

## Box plot

**AstrolBoxPlotSeries**: minimum, quartiles, median and maximum per group.

```razor
@using AstrolCharts

@* Distribution per group: minimum, first quartile, median, third quartile and maximum. *@
<AstrolChart TItem="ResponseTime" Title="Response time by service (ms)" Height="@(320)">
    <AstrolBoxPlotSeries TItem="ResponseTime"
                         Items="times"
                         Name="Response time"
                         XValue="e => e.Service"
                         Min="e => e.Min"
                         Quantile1="e => e.Q1"
                         Median="e => e.Median"
                         Quantile3="e => e.Q3"
                         Max="e => e.Max" />
</AstrolChart>

@code {
    private readonly List<ResponseTime> times = new()
    {
        new() { Service = "Login", Min = 40, Q1 = 60, Median = 75, Q3 = 95, Max = 140 },
        new() { Service = "Search", Min = 80, Q1 = 120, Median = 150, Q3 = 190, Max = 260 },
        new() { Service = "Orders", Min = 55, Q1 = 70, Median = 90, Q3 = 115, Max = 170 },
        new() { Service = "Reports", Min = 200, Q1 = 280, Median = 330, Q3 = 410, Max = 520 },
    };

    public class ResponseTime
    {
        public string Service { get; set; } = string.Empty;
        public decimal Min { get; set; }
        public decimal Q1 { get; set; }
        public decimal Median { get; set; }
        public decimal Q3 { get; set; }
        public decimal Max { get; set; }
    }
}
```


---

# Installation

> AstrolChart: Blazor charts from AstrolUI based on ApexCharts. Lines, areas, bars, circular, radar, heatmaps, ranges, candlesticks and more, with C# data and the AstrolUI light/dark theme.

Source page: https://doc.astrolui.com/chart/installation

**Astrol.Component.Charts** draws charts from C# lists: you say which property goes on each axis and the component does the rest. It works in **Blazor WebAssembly** and **Blazor Server** and is based on [ApexCharts 3.50](https://apexcharts.com) (MIT license).

## 1. Install the package

From the [**AstrolUI NuGet**](https://nuget.astrolui.com/) (source **https://nuget.astrolui.com/v3/index.json**) or by referencing the project in your solution:

```html
dotnet add package Astrol.Component.Charts

<!-- or in the .csproj -->
<PackageReference Include="Astrol.Component.Charts" Version="10.0.13.*" />
```

## 2. Add the namespace

Components and options live in the **AstrolCharts** namespace. Add it to your **_Imports.razor** (or at the top of each page):

```razor
@* _Imports.razor *@
@using AstrolCharts
```

## 3. Theme and scripts

**No chart script or stylesheet is needed**: ApexCharts (≈600 KB) and the chart theme are downloaded automatically the first time a chart is drawn, and pages without charts do not download them. For texts and tooltips to follow the AstrolUI light/dark theme, the app must include the [basic components](/basic-component/installation) stylesheet (it usually already does).

```html
<!-- AstrolUI theme (colors, light/dark mode), shared with the other components -->
<link href="_content/Astrol.Component.Basic/css/astrol-basic.min.css" rel="stylesheet" />

<!-- No longer needed (they can be removed if you are upgrading) -->
<script type="module" src="_content/Astrol.Component.Charts/js/astrolcharts.min.js"></script>
<link href="_content/Astrol.Component.Charts/css/astrolcharts.min.css" rel="stylesheet" />
```

## 4. Your first chart

Continue with the [**AstrolChart**](/chart/chart-component) page: a minimal example, how your data is connected, the series types, the options and the full reference. Then see the examples of [basic charts](/chart/examples/basic), [circular](/chart/examples/circular), [other types](/chart/examples/more), [ranges and finance](/chart/examples/ranges) and [interaction](/chart/examples/interaction); each one has its full code to copy.


---

# Installation

> AstrolPDFViewer is a highly efficient and customizable Blazor component for PDF visualization, offering both traditional and modern options with great configurability and lightweight design.

Source page: https://doc.astrolui.com/pdf-viewer/installation

## 1. Installation process

**AstrolPDFViewer** relies on the [basic components](/basic-component/installation) package of **AstrolUI**.

Install the **Astrol.Component.PDFViewer** package from the [**AstrolUI NuGet**](https://nuget.astrolui.com/) or **reference the project** to your solution.

Add the **AstrolUi NuGet repository** to the **NuGet Package Manager Configuration** of your **Visual Studio**.

**Source:** https://nuget.astrolui.com/v3/index.json [(Refer to documentation on how to configure package sources in Visual Studio)](https://learn.microsoft.com/es-es/nuget/consume-packages/install-use-packages-visual-studio#package-sources)

**No script is needed**: the component loads **pdf.js 4.10.38** (≈1.7 MB) by itself and only when a viewer is on screen, once per app; other pages do not download it. If you are upgrading from an earlier version, **remove** this line from your **index.html** (WebAssembly) or **App.razor / _Host.cshtml** (Blazor Server):

```html
<!-- Remove this line: it is no longer needed -->
<script src="_content/Astrol.Component.PDFViewer/js/astrol-pdf.js"></script>
```


---

# PDFViewer

> AstrolPDFViewer is a highly efficient and customizable Blazor component for PDF visualization, offering both traditional and modern options with great configurability and lightweight design.

Source page: https://doc.astrolui.com/pdf-viewer/pdf-viewer-component

## 1. Demo AstrolPDFViewer

The following buttons **are not part** of the component.

**They are for you to test some visual parameters of the component:**

- **Style** (modern or traditional)
- **Mode** (display all pages at once or one by one)
- **Outline** (dark or light)

```razor
@using Astrol.Component.PDFViewer
@using Astrol.Component.PDFViewer.Helper

<div style="height:600px; width:calc(100% - 10px); float:left; margin:10px 5px;">
   <AstrolPDFViewer PdfUrlOrPath="https://raw.githubusercontent.com/mozilla/pdf.js/ba2edeae/web/compressed.tracemonkey-pldi-09.pdf" />
</div>
```

### Supported parameters

- StylePDFViewer** (StylePDFViewer)**, component style **(default is StylePDFViewer.Modern)**: **Traditional** or **Modern**.
- Outline** (bool)**, controls with a border only, no shadow; colors follow the theme and the light or dark mode **(default is false)**.
- PdfBytes** (byte[]?)**, PDF file as a byte array **(takes precedence over PdfUrlOrPath)**.
- PdfUrlOrPath** (string?)**, URL or path within the app to the PDF file. If it is on another domain, the server must allow **CORS**.
- **A PdfBytes or a PdfUrlOrPath must be set**; changing them opens the document again.
- PresentationMode** (bool)**, shows all pages or one at a time **(default is false)**.
- StartPage** (int)**, starting page **(default is 1)**.
- Scale** (float)**, page size, from **0.25 to 10(default is 1.5F)**.
- Deg** (int)**, page rotation: -270, -180, -90, 0, 90, 180 or 270 **(default is 0)**.
- Load** (RenderFragment)**, custom loading indicator (a spinner by default).
- EnablePagination, EnableRotation, EnableZoom, EnableFullScreen, EnableDownload** (bool)**, show each group of options **(default true)**.
- DocumentNameToDownload** (string)**, file name when downloading **(default DOC (year-month-day).pdf)**. The download uses the document already open, without requesting it from the server again.
- OnPageChange** (EventCallback<int>)**, raised when the page changes with the buttons, the keyboard or **GoToPageAsync**.
- OnScaleChange** (EventCallback<float>)**, raised when the zoom changes.
- OnDegChange** (EventCallback<int>)**, raised when the pages are rotated.
- OnError** (EventCallback<string>)**, raised when the PDF cannot be opened (unreachable URL, CORS or damaged file); the viewer shows a notice.
- Performance: only visible pages (± 400 px) are rendered and far pages release their memory; pages look sharp on high-density screens.
- Keyboard: with the document area focused, **up/down arrows**, **Page Up/Down** and **space** scroll; **left/right** change the page; **Home/End** go to the first/last page. All controls are buttons with an accessible name.
- **Signature** (each viewer is independent) and **IconLoad** (use **Load**) were removed because they had no effect: delete them from your code when upgrading.

### Public methods

- They are used using **@ref** in the **AstrolPDFViewer** component. Example **<AstrolPDFViewer @ref="_pdfViewer" ... />**, declare **_pdfViewer** inside **@code { private AstrolPDFViewer? _pdfViewer; }**.
  - **RefreshAsync**, allows you to refresh the component, especially if the document to be displayed has changed and you need the component to update it without the need for partial or total reload of it or the page.
  - **GoToPageAsync** (receives an int), allows you to change the page.
  - **GetCurrentPage**, allows you to obtain the current page.
  - **GetTotalPage**, allows you to obtain the number of pages of the component.
  - **GetCurrentScale**, allows you to obtain the current scale.
  - **GetCurrentDeg**, allows you to obtain the current orientation degs.


---

# Repository

> Astrol.Shared.Repository is the AstrolUI HTTP client for Blazor: Get, Post, Put, Patch, Delete and file uploads with a response that always tells you whether it failed, the HTTP status and the server message.

Source page: https://doc.astrolui.com/repository

**Astrol.Shared.Repository** wraps **HttpClient** to move data between your Blazor client and your API: it resolves URLs against the API address, sends and reads JSON, uploads files, adds the language and the token, and always returns an **HttpResponseWrapper<T>**. No **try/catch** needed: HTTP errors, network failures and timeouts come back in the result itself.

## 1. Installation process

Install the package and register it in **Program.cs** after the **HttpClient**. The address can be fixed or come from **ClientSetting** (production or development). Relative URLs (**"api/clients"** or **"/api/clients"**) are resolved against that address; if the address has a path, end it with **/** (**https://host/api/**). Absolute **http/https** URLs are accepted too.

```html
dotnet add package Astrol.Shared.Repository
```

```csharp
// Program.cs
using Astrol.Shared.Repository;

builder.Services.AddScoped(sp => new HttpClient { BaseAddress = new Uri(builder.HostEnvironment.BaseAddress) });

// a) Fixed API URL
builder.Services.AddAstrolRepository("https://api.my-app.com/");

// b) From appsettings.json (wwwroot/appsettings.json in WebAssembly)
var clientSetting = builder.Configuration.GetSection("ClientSetting").Get<ClientSetting>()!;
builder.Services.AddAstrolRepository(clientSetting, options =>
{
    options.DefaultLanguage = null;      // null = app language (CultureInfo.CurrentUICulture)
    options.ThrowExceptions = false;     // network errors in the wrapper, no exceptions
    options.UseJsonContext(AppJsonContext.Default);  // source-generated JSON (section 6)
});
```

```html
// wwwroot/appsettings.json
{
  "ClientSetting": {
    "EnvironmentProduction": false,
    "Address": {
      "Development": "https://localhost:7001/",
      "Production": "https://api.my-app.com/"
    }
  }
}
```

## 2. Demo IRepository

This documentation registers the repository with its own address. The buttons read a JSON file from the site, request a file that does not exist (404) and call a server that is down (network failure): none of them throws an exception.

```razor
@using Astrol.Shared.Repository
@inject IRepository Repository

<AstrolButton Text="Read JSON" OnClick='() => Load("sample-data/clients.json")' />
<AstrolButton Text="Error 404" OnClick='() => Load("sample-data/missing.json")' />
<AstrolButton Text="No connection" OnClick='() => Load("http://localhost:9/api/clients")' />

@if (_result is not null)
{
    <div>IsSuccess: @_result.IsSuccess</div>
    <div>StatusCode: @_result.StatusCode</div>
    <div>IsNetworkError: @_result.IsNetworkError</div>
    <div>ErrorMessage: @_result.ErrorMessage</div>
}
@code {
```

```csharp
   private HttpResponseWrapper<List<ClientDto>>? _result;

   private async Task Load(string url) {
       _result = await Repository.Get<List<ClientDto>>(url);
   }

   public class ClientDto {
       public int Id { get; set; }
       public string? FullName { get; set; }
       public decimal Points { get; set; }
   }
}
```

## 3. Usage and error handling

Inject **IRepository** and check **IsSuccess** (or **Error**). When it failed, **ErrorMessage** already has a message ready to show, **StatusCode** the HTTP status (**null** when there was no response) and **IsNetworkError** tells whether the server did not answer.

```csharp
@inject IRepository Repository
@inject IAstrolToast Toast

// GET: list, object, text (Get<string>) or file (Get<byte[]>)
var clients = await Repository.Get<List<ClientDto>>("api/clients?page=1");
if (clients.IsSuccess) _clients = clients.Response;
else Toast.Error(clients.ErrorMessage!);

// POST / PUT / PATCH without and with a response
var saved = await Repository.Post("api/clients", newClient);
var created = await Repository.Post<ClientDto, ClientDto>("api/clients", newClient);
var updated = await Repository.Put<ClientDto, ClientDto>($"api/clients/{id}", client);
var patched = await Repository.Patch($"api/clients/{id}", new { FullName = "Ana" });

// DELETE
var deleted = await Repository.Delete($"api/clients/{id}");

// Telling errors apart
if (deleted.IsNetworkError) Toast.Warning("No connection to the server.");
else if (deleted.StatusCode == HttpStatusCode.Unauthorized) Navigation.NavigateTo("/login");
else if (deleted.Error) Toast.Error(deleted.ErrorMessage!);

// Language and cancellation (e.g. when leaving the page)
var result = await Repository.Get<ClientDto>("api/clients/1", "en", _cts.Token);

// Any other content or method
var csv = await Repository.Send<string>(HttpMethod.Post, "api/report", new StringContent("a;b"));
```

## 4. Uploading files

**Post<TResponse>(url, files)** and **Put<TResponse>(url, files)** send a list of **IBrowserFile** (for example the one from [AstrolUploadFile](/basic-component/upload-file)) as **multipart/form-data**. Use **fieldName** to change the field name and **fields** to add text fields.

```razor
<AstrolUploadFile Status="@_statusUpload" Save="SaveFiles" OnClose="s => _statusUpload = s" />
@code {
```

```csharp
   private bool _statusUpload;

   private async Task SaveFiles(List<IBrowserFile> files) {
       var result = await Repository.Post<List<string>>("api/documents", files,
           fieldName: "files",                                                  // form field name (default "files")
           fields: new Dictionary<string, string> { ["folder"] = "invoices" });  // extra text fields

       if (result.Error) throw new Exception(result.ErrorMessage); // AstrolUploadFile shows it as an error
       _statusUpload = false;
   }
}
```

```csharp
// API (ASP.NET Core)
[HttpPost("api/documents")]
public async Task<List<string>> Upload([FromForm] List<IFormFile> files, [FromForm] string folder) { ... }
```

## 5. Authentication token

Register an implementation of **IRepositoryTokenProvider** and every request will carry **Authorization: Bearer {token}**. Do not modify **HttpClient.DefaultRequestHeaders**: the **HttpClient** is shared by the whole app.

```csharp
public class TokenProvider : IRepositoryTokenProvider
{
    private readonly IJSRuntime _js;
    public TokenProvider(IJSRuntime js) => _js = js;

    // null or empty = the request is sent without a token
    public async ValueTask<string?> GetTokenAsync(CancellationToken cancellationToken = default)
        => await _js.InvokeAsync<string?>("localStorage.getItem", cancellationToken, "token");
}

// Program.cs
builder.Services.AddScoped<IRepositoryTokenProvider, TokenProvider>();
builder.Services.AddAstrolRepository(clientSetting);
```

## 6. Performance: source-generated JSON

By default JSON is read and written with **reflection**: in WebAssembly each type has to be analyzed in the browser the first time it is used, which delays the first load of each screen, and reflection prevents **trimming** from shrinking the app. With **UseJsonContext**, the types you declare in a **JsonSerializerContext** use code generated at compile time: no reflection and faster from the first call.

- No call and no JSON changes: names follow the policy of **RepositoryOptions.JsonSerializerOptions** (camelCase), not the context's **JsonSourceGenerationOptions**.
- Types that are not in the context (e.g. anonymous types in **Patch**) keep working with reflection, unless the app turns it off (**JsonSerializerIsReflectionEnabledByDefault=false**).
- Declare the types in **.cs** files, not inside a **.razor** (**@code**): the JSON generator cannot see classes declared in components.
- This documentation uses it: the demo above reads **List<ClientDto>** with generated code.

```csharp
using System.Text.Json.Serialization;

// One class per project: list every type you send or read with IRepository
// (also the collections: List<ClientDto>, ClientDto[] ...).
[JsonSerializable(typeof(ClientDto))]
[JsonSerializable(typeof(List<ClientDto>))]
[JsonSerializable(typeof(UserToken))]
internal partial class AppJsonContext : JsonSerializerContext
{
}

// Program.cs
builder.Services.AddAstrolRepository(clientSetting, options => options.UseJsonContext(AppJsonContext.Default));
```

### Supported parameters

**IRepository** (every method accepts optional **language** and **cancellationToken**):

- **Get<T>(url)**: reads JSON; with **T = string** it returns the text and with **T = byte[]** the bytes (downloads).
- **Post<T>(url, data)**, **Put<T>**, **Patch<T>**: send **data** as JSON without reading the response.
- **Post<T, TResponse>(url, data)**, **Put<T, TResponse>**, **Patch<T, TResponse>**: send JSON and read the response.
- **Delete(url)** and **Delete<T>(url)**.
- **Post<TResponse>(url, files, fieldName = "files", fields = null)** and **Put<TResponse>(...)**: files as **multipart/form-data**.
- **Send<TResponse>(method, url, content)**: any method and any **HttpContent**.
- **language** (string): **Accept-Language** header; **null** (default) uses the app language.
- **cancellationToken**: cancels the request; cancellation is thrown as **OperationCanceledException**.

**HttpResponseWrapper<T>**:

- **IsSuccess** / **Error** (bool): result of the request.
- **Response** (T): content read; **default** when it failed or the response was empty (204).
- **StatusCode** (HttpStatusCode?): HTTP status; **null** when there was no response.
- **ErrorMessage** (string): **detail** or **title** of a ProblemDetails, the validation **errors** messages (one per line), **message**/**error** of a JSON, the body text or the HTTP status.
- **IsNetworkError** (bool): the server could not be reached (offline, DNS, CORS or timeout).
- **Exception** (Exception): captured exception (network, timeout or invalid JSON).
- **HttpResponseMessage** and **GetBody()**: the original response and its body as text (can be read several times). On a network failure it is a 503 response (408 on a timeout).

**RepositoryOptions** (**AddAstrolRepository(url, options => ...)**):

- **JsonSerializerOptions**: **JsonSerializerDefaults.Web** by default (camelCase, case-insensitive). Set **TypeInfoResolver** to use source-generated JSON (faster and lighter in WebAssembly).
- **UseJsonContext(context)**: uses source-generated JSON for the context types (see section 6).
- **DefaultLanguage** (string): language when the call does not give one (default **null** = current culture).
- **ThrowExceptions** (bool): **true** throws network failures, timeouts and invalid JSON as before (default **false**).
- **AuthorizationScheme** (string): token scheme (default **Bearer**).
- **ConfigureRequest** (Action<HttpRequestMessage>): to add your own headers to every request.


---

# Installation

> AstrolRichText is a dynamic Blazor component that elevates the presentation of textual content to new heights. Unlike a simple text field, it allows for advanced formatting such as bold, italic, numbered or bulleted lists, enriching expression and style. This versatile tool is particularly useful for creating diverse content, from blog entries to detailed documents, providing users with the ability to express themselves with greater flexibility and expressiveness. Content creation becomes more intuitive and visually appealing.

Source page: https://doc.astrolui.com/rich-text/installation

## 1. Installation process

For the proper use of this package, you must have the [basic components package](/basic-component/installation) from **AstrolUI** installed and configured beforehand.

Install the **Astrol.Component.RichText** package from the [**AstrolUI NuGet**](https://nuget.astrolui.com/) or **reference the project** in your solution.

Add the **NuGet AstrolUi** repository in the **NuGet Package Manager settings** of your **Visual Studio**.

**Source:** https://nuget.astrolui.com/v3/index.json [(Refer to documentation on how to configure package sources in Visual Studio)](https://learn.microsoft.com/es-es/nuget/consume-packages/install-use-packages-visual-studio#package-sources)

**No .css or .js is needed**: the editor (Quill, ≈265 KB) is downloaded only when an **AstrolRichText** is on screen, once per app; other pages do not download it. If you are upgrading from an earlier version you can **remove** these lines from your **index.html** (WebAssembly) or **App.razor / _Host.cshtml** (Blazor Server); if you keep them, nothing is loaded twice:

```html
<!-- No longer needed: they can be removed -->
<link href="_content/Astrol.Component.RichText/css/astrol-rich-text.min.css" rel="stylesheet" />
<script src="_content/Astrol.Component.RichText/js/astrol-rich-text.min.js"></script>
```


---

# RichText

> AstrolRichText is a dynamic Blazor component that elevates the presentation of textual content to new heights. Unlike a simple text field, it allows for advanced formatting such as bold, italic, numbered or bulleted lists, enriching expression and style. This versatile tool is particularly useful for creating diverse content, from blog entries to detailed documents, providing users with the ability to express themselves with greater flexibility and expressiveness. Content creation becomes more intuitive and visually appealing.

Source page: https://doc.astrolui.com/rich-text/rich-text-component

## 1. Demo AstrolRichText

In this example, [buttons](/basic-component/button), [modal](/basic-component/modal), and [the loading component](/basic-component/load) are implemented, so it is recommended to refer to the corresponding documentation.

**If you have ad blockers in your browser, it may affect the component's behavior.**

```razor
@using Astrol.Entities.Basic.UI
@using Astrol.Component.RichText
@using Astrol.Component.Basic.Button
@using Astrol.Component.Basic.Modal
@using Astrol.Component.Basic.Load

<AstrolLoad Status="_load" />
<AstrolModal Title="HTML content" Status="_statusModal">
   <div style="text-align:left; padding:20px;">
       @((MarkupString) _htmlContent)
   </div>
</AstrolModal>

<div style="padding:5px;">
   <AstrolRichText @ref="_astrolRichText"
                   MaxHeight="220px"
                   Placeholder="Enter your text here." />
   <AstrolButton OnClick="GetHTML"
                 Style="AstrolStyle.Blue"
                 Text="Get HTML"
                 Icon="astrol-code-1" />
</div>
@code {
```

```csharp
   private string _htmlContent = "";
   private bool _statusModal = false;
   private bool _load = false;
   private AstrolRichText? _astrolRichText;
   public async Task GetHTML()
   {
       _load = true;
       if (_astrolRichText != null)
           _htmlContent = await _astrolRichText.GetHTMLAsync();
       _statusModal = true;
       _load = false;
   }
}
```

### Supported parameters

- **ReadOnly** (bool), defines whether the component is in read-only mode (default is **false**).
- **IsBottomToolbar** (bool), defines if the options bar is displayed at the bottom (default is **false**).
- **MinHeight** (string), minimum height (default is **150px**). MinHeight and MaxHeight apply to each editor separately.
- **MaxHeight** (string), maximum height (default is **200px**).
- **Placeholder** (string), text to display in the component's placeholder (not required).
- **ToolbarClass** (string), CSS class to define for the options bar (not required).
- **ContentClass** (string), CSS class to define for the content (not required).
- The options bar is accessible: every button has a name and does not submit forms (**type="button"**).
- **FullRender** (EventCallback), event that notifies when the component has loaded completely (not required).
- Configuration of the options bar, all of type **(bool)**, allowing them to be disabled as all are set to **true** by default:
  - ShowFont
  - ShowSize
  - ShowBold
  - ShowItalic
  - ShowUnderline
  - ShowStrike
  - ShowColor
  - ShowBackground
  - ShowListOrdered
  - ShowListBullet
  - ShowIndentPlus
  - ShowIndentLess
  - ShowAlign
  - ShowHeader1
  - ShowHeader2
  - ShowBlockquote
  - ShowCodeBlock
  - ShowScriptSub
  - ShowScriptSuper
  - ShowFormula (requires [KaTeX](https://katex.org) loaded on the page; without it the button is hidden)
  - ShowLink
  - ShowImage
  - ShowVideo

### Public methods

- **GetTextAsync**, allows you to retrieve the text written in the component (returns a **string**).
- **GetHTMLAsync**, allows you to retrieve the HTML content of the component (returns a **string**).
- **GetContentAsync**, allows you to retrieve the content (JSON) of the component (returns a **string**).
- **SetContentAsync**, allows you to insert content (JSON) into the component (takes a **string** as input).
- **SetHTMLAsync**, replaces the content with HTML (takes a **string**). It is converted to the formats the editor supports and scripts, event attributes (**onerror**, **onclick**...) and **javascript:** links are removed, so it is safe with user HTML.
- **SetTextAsync**, allows you to insert text into the component (takes a **string** as input).
- **SetStatusAsync**, allows you to set or modify the state of the component (takes a **bool** as input).
- **InsertImageAsync**, allows you to insert an image into the component (takes a **string** representing the image URL).
- **InsertVideoAsync**, allows you to insert a video into the component (takes a **string** representing the video URL).


---

# PERENDER

> PERENDER: rendering and caching engine that makes SPAs (Blazor, Angular, React...) indexable for search engines, AI and social networks, with articles, categories, hosted sitemaps and indexing rules.

Source page: https://doc.astrolui.com/perender

Rendering, caching and SEO for SPA applications.

PERENDER** is a **rendering and caching** engine so search engines, AI bots and social networks see your SPA as a complete HTML page. It also includes content and SEO tools: **articles**, **categories or article groups**, **hosted sitemaps** and **indexing rules**. Human visitors keep using your normal app: PERENDER only answers bots.

## 1. The SPA problem

In a SPA the initial HTML is almost empty and the content is built by JavaScript in the browser (in Blazor WebAssembly the .NET runtime is downloaded first, too). Many bots don't run JavaScript, or run it late and with limits: the result is incomplete indexing, generic titles and descriptions, and empty previews when a link is shared.

Prerendering hands each bot an already rendered HTML version of the page, with its content and its **meta** and **Open Graph** tags, without changing anything in the app.

## 2. How it works

## 3. What it includes

## 4. Integrations

Choose where to detect bots. The closer to the user the better: the request never reaches your server.

## 5. API

Every integration calls the same endpoint, **https://api.perender.com/render**, with two parameters: **url** (the page to render, cache or return) and **botAgent** (the detected bot). Each request carries the **PERENDER_TOKEN** (a JWT you get, and can regenerate, in the dashboard) in the **Authorization** header. Never expose it on the client: keep it as a Worker or server variable and regenerate it if it leaks.

Integrations add the **X-Perender** header to avoid loops and skip static assets (.js, .css, images, fonts...).

```bash
curl -X GET "https://api.perender.com/render?url=https%3A%2F%2Fexample.com&botAgent=integration-test" \
     -H "accept: */*" -H "Authorization: Bearer [PERENDER_TOKEN]"
```

```javascript
// Cloudflare Worker (summary). Full code: github.com/perender/perender-cloudflare-worker
const isBot = BOT_AGENTS.find(bot => userAgent.includes(bot));
if (request.headers.get("X-Perender") || !isBot || IGNORE_EXTENSIONS.includes(extension)) {
    return fetch(request); // people and static files: served as usual
}
const url = `https://api.perender.com/Render?url=${request.url}&botAgent=${encodeURIComponent(isBot)}`;
const headers = new Headers(request.headers);
headers.set("Authorization", `Bearer ${env.PERENDER_TOKEN}`); // Worker variable, never in the client
return fetch(new Request(url, { headers, redirect: "manual" }));
```

## 6. Tips for SPAs built with AstrolUI

- Give every page its own **<PageTitle>** and **<HeadContent>** with description and Open Graph (AstrolTitle accepts HeadContent): PERENDER keeps them in the rendered HTML.
- Use a URL of its own for each piece of content and each language (like /perender and /perender/es in these docs) and add them to the sitemap.
- Don't make the main content depend on a click or a scroll: what isn't painted on load isn't indexed.
- After publishing important changes, re-cache from the dashboard.

```razor
<PageTitle>Product X | MyStore</PageTitle>
<AstrolTitle Icon="astrol-basket" Text="Product X">
    <HeadContent>
        <meta name="description" content="Short description that will appear in Google" />
        <meta property="og:title" content="Product X" />
        <meta property="og:description" content="Preview text for WhatsApp, LinkedIn, X..." />
        <meta property="og:image" content="https://mystore.com/img/product-x.jpg" />
        <link rel="canonical" href="https://mystore.com/product/x" />
    </HeadContent>
</AstrolTitle>
```

## 7. Links