Conventions

The rules every StellarAdmin Tag Helper follows for attributes, classes, model binding and links

All the StellarAdmin.UI Tag Helpers follow the conventions on this page. The API Reference section of each component page lists only what's specific to that component.

Passing attributes to the rendered element

Each Tag Helper renders a standard HTML element, such as a <button> or a <div>. The API Reference section of a component page lists the attributes the Tag Helper uses, and says which element it renders. The Tag Helper passes any other attribute you specify, unchanged, to that element. These include:

  • The global HTML attributes, such as id, style, title and hidden.
  • data-* and aria-* attributes.
  • The attributes of the rendered element, such as href and target on an <a>, or type, name, disabled and placeholder on an <input>.
  • Event handler attributes, and the attributes of libraries such as htmx and Alpine.js.

In the example below, the Button Tag Helper uses the variant and size attributes. It passes id, type, form, data-testid and hx-post to the <button> element.

<sa-button variant="ButtonVariant.Outline" size="ButtonSize.Large"
           id="save" type="submit" form="booking-form"
           data-testid="save-button" hx-post="/bookings">
    Save
</sa-button>

Some Tag Helpers render more than one element. Their API Reference section says which element gets the attributes. For example, the table puts class on the <table>, and the other attributes on the element that scrolls it.

Adding your own classes

Each Tag Helper styles its element with its own CSS classes. The classes you specify in the class attribute are added after them. For example, the following card:

<sa-card class="trip-card">...</sa-card>

renders the following <div>:

<div data-slot="card" data-size="default" class="sa-card trip-card">...</div>

Use your own classes for layout and spacing, and style them in your own stylesheet. To match the theme, use the design tokens in your CSS.

The StellarAdmin.UI stylesheet doesn't contain utility classes, such as w-full or mt-4. If your app has its own Tailwind CSS build, its utility classes work on the Tag Helpers too. To make them use the theme's colors and spacing, add the Tailwind adapter.

Binding to the model

The form Tag Helpers take an asp-for attribute, and work like the built-in ASP.NET Core Tag Helpers:

  • The name, id and value come from the bound property.
  • The validation state comes from ModelState.
  • The label, the description and the placeholder come from the property's [Display] attribute.

Linking to pages

The Tag Helpers that render an <a> element, such as the link button and the breadcrumb, pagination, tab and dropdown menu links, take either an href or the ASP.NET Core routing attributes, such as asp-page, asp-controller, asp-action and asp-route-*. The built-in anchor Tag Helper resolves the routing attributes, so they work the same as on an <a>.

On this page