Best Practices

Start with Styled Components

Always reach for NeoUI.Blazor styled components first. They have beautiful defaults, full theme support, and accessibility built in. Only drop to the Primitives layer when you need complete control over markup and styling — for example, when building a bespoke component that must match a custom design system that differs from shadcn/ui.

Use the AsChild Pattern for Triggers

When you want a styled Button to trigger an overlay, use AsChild on the trigger component. This lets you compose any button variant without wrapping it in an extra element or overriding default trigger styles:

@* Without AsChild — renders an extra default <button> wrapper *@
<DialogTrigger>Open</DialogTrigger>

@* With AsChild — your Button IS the trigger, no extra element *@
<DialogTrigger AsChild>
    <Button Variant="ButtonVariant.Destructive">Delete account</Button>
</DialogTrigger>

This pattern applies to DialogTrigger, PopoverTrigger, SheetTrigger, DropdownMenuTrigger, and all other trigger components.

Form Composition

Wrap related fields in FieldGroup — it spaces out multiple fields with consistent vertical rhythm. Wrap each individual control in Field to compose the label, control, help text, and validation message as a single accessible unit.

Always set For on FieldLabel to match the Id of the focusable input beneath it. This wires the HTML for attribute correctly so clicking the label focuses the right control.

Set ShowValidationError="true" on any input component to enable built-in EditForm validation integration. On submit, the component automatically applies error styling, the first invalid field is focused, and a validation tooltip with the error message appears inline — no separate FieldMessage required.

<EditForm Model="@_model" OnValidSubmit="HandleSubmit">
    <DataAnnotationsValidator />

    @* FieldGroup spaces multiple Field components with consistent vertical rhythm *@
    <FieldGroup>

        @* FieldLabel.For matches the Id of the focusable input below it *@
        <Field>
            <FieldLabel For="full-name">Full name</FieldLabel>
            <FieldControl>
                @* ShowValidationError: applies error style + auto-focuses first error + shows tooltip *@
                <Input Id="full-name" @bind-Value="_model.Name" ShowValidationError="true" />
            </FieldControl>
        </Field>

        <Field>
            <FieldLabel For="email">Email address</FieldLabel>
            <FieldControl>
                <Input Id="email" @bind-Value="_model.Email"
                       Type="InputType.Email" ShowValidationError="true" />
            </FieldControl>
            <FieldDescription>We'll never share your email.</FieldDescription>
        </Field>

        <Field>
            <FieldLabel For="role">Role</FieldLabel>
            <FieldControl>
                <Select Id="role" @bind-Value="_model.Role" ShowValidationError="true">
                    <SelectTrigger />
                    <SelectContent>
                        <SelectItem Value="admin">Admin</SelectItem>
                        <SelectItem Value="member">Member</SelectItem>
                    </SelectContent>
                </Select>
            </FieldControl>
        </Field>

        <Field>
            <FieldLabel For="budget">Budget</FieldLabel>
            <FieldControl>
                <NumericInput Id="budget" @bind-Value="_model.Budget"
                              Prefix="$" ShowValidationError="true" />
            </FieldControl>
        </Field>

        <Field>
            <FieldLabel For="start-date">Start date</FieldLabel>
            <FieldControl>
                <DatePicker Id="start-date" @bind-Value="_model.StartDate"
                            ShowValidationError="true" />
            </FieldControl>
        </Field>

        <Field>
            <FieldLabel For="notify">Email notifications</FieldLabel>
            <FieldControl>
                <Switch Id="notify" @bind-Value="_model.Notifications" />
            </FieldControl>
        </Field>

    </FieldGroup>

    <Button Type="ButtonType.Submit" Class="mt-2">Save</Button>
</EditForm>

Theme Management in Production

• Ship only the theme files you use. If your app uses a fixed theme, include only one base and one primary CSS file. This avoids loading 22 theme files for users who cannot switch.
• Always load theme CSS before components.css. NeoUI reads the CSS variables at component render time. If variables aren't defined yet the components fall back to browser defaults.
• Include theme.js in <head>, not deferred. The script applies the saved theme class before paint to prevent a flash of unstyled content.
• Use @Assets[...] for all static web asset references in App.razor. .NET 10 adds a fingerprint hash for cache busting on each deployment.

Don't Fight the Defaults

NeoUI components come with carefully considered defaults for accessibility, focus management, and keyboard behavior. Before adding custom JavaScript or overriding ARIA attributes, check whether the component already supports the behavior you need — it often does via a parameter. Overriding built-in accessibility handling is the most common source of regressions.

Use a Single Icon Library

All three icon libraries are included transitively with NeoUI.Blazor, but pick one and use it consistently throughout your application. Mixing Lucide, Heroicons, and Feather in the same UI creates visual inconsistency — different stroke weights, viewBox sizes, and design languages. NeoUI itself uses Lucide everywhere.

FAQ