Imported from Maviray/blazor-ui-kit (.claude/skills/maviray-blazor-components/SKILL.md). Install upstream with npx skills add Maviray/blazor-ui-kit --skill maviray-blazor-components. Copyright stays with the author.

Maviray Blazor Material Components

Overview

Maviray.Blazor.Components.Material is a Blazor component library (Mavi* components) providing themed, accessible, Material-Design UI building blocks. It targets .NET 8/9/10 and ships as a NuGet package with its own CSS + JS assets.

Core principle for consuming projects: reach for a Mavi* component first. Almost every common UI need — inputs, buttons, dialogs, tables, menus, tabs, cards, alerts, toasts, spinners — already exists here, wired for theming, validation, and accessibility. Do not hand-roll <input>, <button>, <table>, <dialog>, dropdown, or modal markup when a component covers it. Configure the component through its strongly-typed parameters instead.

This skill documents the components' API surface (parameters, methods, events, data models). For color/typography/spacing/Tailwind decisions, use the companion material-css-styling skill.

When to use

• Adding or editing any screen, form, list, dialog, or interactive element
• Choosing which Mavi* component fits a need ("is there a component for X?")
• Configuring a component's parameters, wiring its events, or calling its methods
• Feeding data into the table, menu, autocomplete, dropdown, or toast components
• Reviewing whether existing custom markup should be replaced by a component

"I need X" → component quick lookup

Setup (consuming project)

1. Register services — in Program.cs:

   using Maviray.Blazor.Components.Core.Extensions;
   
   builder.Services.AddMaviComponents();
   // or configure options:
   builder.Services.AddMaviComponents(o =>
   {
       o.ComponentLogLevel = LogLevel.Warning;   // default
       o.EnableLifecycleLogging = false;         // default
       o.EnablePerformanceTracking = false;      // default
   });

   This registers IMaviComponentOptions. Components resolve it (and an ILoggerFactory) via DI; without registration they still render but lifecycle logging/options are unavailable.

2. Include the CSS — reference the packaged stylesheet from the host document (App.razor / index.html / _Host.cshtml):

   <link rel="stylesheet"
         href="_content/Maviray.Blazor.Components.Material/css/maviray.material.min.css" />

   (maviray.material.min.css is the compiled Tailwind 4 build of the theme + component styles. See material-css-styling for the token system.)

3. JS interop — a few components lazy-load their own ES modules from _content/Maviray.Blazor.Components.Material/js/ on first render (MaviDropdown/MaviMultiSelect → maviDropDownJsInterop.js, MaviInputDate* → maviDatePickerJsInterop.js; WysiwygEditor → maviWysiwygJsInterop.js). Components using outside-click detection (MaviDropDownMenu, WysiwygEditor, the tables) call helpers in maviJsInterop.js; ensure that script is available to the host. Follow the samples/Maviray.Blazor.Components.Samples.Material project for the canonical host wiring.

4. @using namespaces — components live under Maviray.Blazor.Components.Material.Components.* (see below). Add the namespaces you use to the consuming project's _Imports.razor, e.g.:

   @using Maviray.Blazor.Components.Material.Components.Inputs
   @using Maviray.Blazor.Components.Material.Components.Feedback
   @using Maviray.Blazor.Components.Core.Enums
   @using Maviray.Blazor.Components.Core.Models

Namespaces

Shared conventions (read once — they apply to most components)

Base parameters every component has

All components derive from MaviComponentBase, which provides:

Components deriving from MaviAttributesComponent (buttons, button group) additionally capture unmatched attributes into AdditionalAttributes (@attributes splat) so you can pass arbitrary HTML attributes.

Form-input base surface

Form inputs derive from MaviInputBase<TValue> (which extends Blazor's InputBase<TValue>, so @bind-Value and EditForm/EditContext validation work) → MaviMaterialInputBase<TValue>. Common parameters shared by every text, numeric, select, and date input:

Attribute inference (when InferFromModelAttributes is true) reads the bound property's annotations: [Display]/[DisplayName] → Label, [Required] → Required, plus per-type inference ([MaxLength]/[StringLength] → MaxLength; [DataType] → StringInputType/DateInputType; [Range] → Min/Max).

Programmatic validation (on any Material input, via @ref):

• void SetError(string message) — mark the field invalid with the standard red/alert visual state and register the message on the EditContext (surfaces in a ValidationSummary). Auto-clears on the next value change.
• void ClearError() — clear a programmatic error explicitly.

Use these inside an OnValidSubmit handler when a check can't be expressed as a data annotation.

Shared enums (Maviray.Blazor.Components.Core.Enums)

The component ThemeColorScheme enum covers a subset of the CSS theme roles — it has no Tertiary/Accent/Highlight. See material-css-styling.

Common event payloads (Maviray.Blazor.Components.Core)

• ValueChangedCallbackParameters<T> — { string? ElementId; T? Value; }. Many components expose a secondary …StatusChange/…ValueChanged/ OnSelectionChanged callback of this type carrying the source Id.
• MouseClickEventArgs — extends MouseEventArgs with ButtonId. Emitted by OnClick on buttons, links, badges, etc.
• MouseGroupClickEventArgs — adds the clicked child button id (button group).
• TabClickEventArgs, DialogButtonClickEventArgs, ButtonClickEventArgs — used by tabs, dialog, and the circuit-state service respectively.

Reference files (read the one for the component you're using)

Each file lists the components in that area with their specific parameters, public methods, events, data models, and a usage snippet. The shared surface above is not repeated there.

• references/inputs-forms.md — text, numeric, textarea, checkbox, switch, toggle, radio, dropdown, multi-select, autocomplete, date, slider, validation message.
• references/buttons-actions.md — MaviButton, MaviButtonIcon, MaviButtonGroup, MaviLink.
• references/data-display.md — MaviBadge, MaviChip, icon components.
• references/feedback-overlays.md — MaviAlert, MaviToastr, MaviDialog, MaviBackdrop, MaviSkeleton, spinners.
• references/layout-navigation.md — surfaces (accordion, card, panel), tabs, menus, top nav bar, error handler.
• references/tables.md — MaviInMemoryTable, MaviCssGridTable, and the table data model (ITableDataItem, [TableColumn], TableDataCollection, TableParameters, context menus, events).
• references/editors.md — WysiwygEditor (rich-text / HTML editor): toolbar, parameters, @bind-Content, public methods, and gotchas.

Component usage pattern (the shape of almost every component)

@* Configure with strongly-typed enum parameters; extend look via Class *@
<MaviButton Title="Save"
            ThemeColorScheme="ThemeColorScheme.Primary"
            ElementVariant="ElementVariant.Filled"
            ElementSize="ElementSize.Regular"
            OnClick="HandleSaveAsync"
            Class="w-full mt-4" />

@* Inputs bind with @bind-Value and live in an EditForm for validation *@
<EditForm Model="_model" OnValidSubmit="SubmitAsync">
    <DataAnnotationsValidator />
    <MaviInputString @bind-Value="_model.Name" Width="w-96" />
    <MaviInputInteger @bind-Value="_model.Age" Min="0" Max="120" />
    <MaviButton ButtonRole="ButtonRole.Submit" Title="Submit"
                ThemeColorScheme="ThemeColorScheme.Primary" />
</EditForm>

Rules of thumb

• Configure via enum parameters; never rebuild a component's internals.
• Extend appearance via Class (appended to computed classes), not by forking.
• Bind data inputs with @bind-Value; place them in an EditForm for validation and let attribute inference fill Label/Required.
• Hold an @ref to call imperative methods (Display/Hide on dialogs, toasts, backdrops, alerts; SetError/ClearError on inputs; Refresh on tables; Reset/SetSelection on autocomplete).
• Pointers: components live in src/Maviray.Blazor.Components.Material/Components/**; enums/models in src/Maviray.Blazor.Components.Core/**; living examples in samples/Maviray.Blazor.Components.Samples.Material.Client/Pages/**.