Radio group

<sa-radio-group name="intro-radio" value="express" label="Delivery">
    <sa-radio-group-item value="standard" description="Arrives in five days">Standard</sa-radio-group-item>
    <sa-radio-group-item value="express" description="Arrives tomorrow">Express</sa-radio-group-item>
</sa-radio-group>

UsageCopy Anchor Link

Prefer a radio group when related options share one bound property, label, and validation message. Use normal radio inputs when you need to compose the fields and layout yourself.

Use <sa-radio-group> with <sa-radio-group-item> children to render a labeled group. Each item uses its content as the label and accepts an optional description. Both display variants use the existing Field and Input markup.

Use asp-for for model binding, or name and value for a group without model binding. Option value attributes are strings, including values such as value="1" that bind to numeric properties. MVC converts submitted values to the model type. Values must be unique within the group.

ExamplesCopy Anchor Link

Model bindingCopy Anchor Link

Bind to a scalar string, enum, Guid, bool, or numeric primitive, including nullable value types. Use a nullable property with [Required] to require a selection.

Labels and descriptions are derived from [Display] metadata. Submitted ModelState values take precedence when redisplaying the form. Do not combine asp-for with name or value. Date/time and complex model types are not supported.

<sa-radio-group asp-for="DeliveryMethod">
    <sa-radio-group-item value="@Index.Delivery.Standard" description="Arrives in five days">Standard</sa-radio-group-item>
    <sa-radio-group-item value="@Index.Delivery.Express" description="Arrives tomorrow">Express</sa-radio-group-item>
</sa-radio-group>

The example binds to this model property:

[Display(Name = "Delivery method", Description = "Choose how we deliver your order.")]
[Required(ErrorMessage = "Choose a delivery method.")]
public Delivery? DeliveryMethod { get; set; } = Delivery.Standard;

public enum Delivery
{
    Standard,
    Express,
}

In a Razor Page, expose the containing model with [BindProperty] to receive form submissions. These exported previews demonstrate the rendered state; the DocsSamples application contains the working POST form.

Choice cardsCopy Anchor Link

Set variant="RadioGroupVariant.ChoiceCard" to make each option a clickable card. The default is RadioGroupVariant.Default.

<sa-radio-group name="choicecards-radio" value="express" label="Delivery" variant="RadioGroupVariant.ChoiceCard">
    <sa-radio-group-item value="standard" description="Arrives in five days">Standard</sa-radio-group-item>
    <sa-radio-group-item value="express" description="Arrives tomorrow">Express</sa-radio-group-item>
</sa-radio-group>

ItemsCopy Anchor Link

Use asp-items with SelectListItem objects as an alternative to child tags. Selected sets the initial selection for an unbound group when value is not supplied. Disabled disables an individual option. Do not combine asp-items with child items; SelectListGroup is not supported.

<sa-radio-group name="items-radio" label="Options"
    asp-items="@([new SelectListItem("First option", "first", true), new SelectListItem("Second option", "second")])" />

MediaCopy Anchor Link

Put a <sa-radio-group-item-media> inside an item to show an icon, avatar, image or other media with the option. The media sits before the option's text, or leads the card in the choice card variant. Size the media with classes on its content. Use one media tag per item; options supplied with asp-items have no media. This example adds avatars to choice cards.

<sa-radio-group name="media-radio" value="ana" label="Tour guide" variant="RadioGroupVariant.ChoiceCard">
    <sa-radio-group-item value="ana" description="Lisbon walking tours">
        <sa-radio-group-item-media><sa-avatar src="/avatars/avatar-1.jpg" /></sa-radio-group-item-media>
        Ana Ferreira
    </sa-radio-group-item>
    <sa-radio-group-item value="yuki" description="Kyoto temples and gardens">
        <sa-radio-group-item-media><sa-avatar src="/avatars/avatar-2.jpg" /></sa-radio-group-item-media>
        Yuki Tanaka
    </sa-radio-group-item>
</sa-radio-group>

ColumnsCopy Anchor Link

Set columns to show the options in columns at every width, or columns-sm, columns-md and columns-lg to set the number of columns once the field is at least 30rem, 40rem and 56rem wide; a width without a value uses the value of the next smaller width, and columns defaults to one column. The widths are measured against the field, so a group in a narrow column of an <sa-grid> stays in one column. The options fill each row in turn; set flow="RadioGroupFlow.Down" to fill each column from top to bottom before the next.

<sa-radio-group name="columns-radio" label="Cabin" columns-sm="2" value="premium"
    variant="RadioGroupVariant.ChoiceCard">
    <sa-radio-group-item value="economy" description="A seat, a meal and a bag.">Economy</sa-radio-group-item>
    <sa-radio-group-item value="premium" description="Extra legroom and priority boarding.">Premium economy</sa-radio-group-item>
    <sa-radio-group-item value="business" description="Lie-flat seats and lounge access.">Business</sa-radio-group-item>
    <sa-radio-group-item value="first" description="A private suite and chauffeur transfer.">First</sa-radio-group-item>
</sa-radio-group>

ValidationCopy Anchor Link

The group displays one ModelState error and marks its inputs invalid. StellarAdmin does not provide client-side validation; use server-side validation or add your own client validation.

<sa-radio-group asp-for="DeliveryMethod">
    <sa-radio-group-item value="Standard" description="Arrives in five days">Standard</sa-radio-group-item>
    <sa-radio-group-item value="Express" description="Arrives tomorrow">Express</sa-radio-group-item>
</sa-radio-group>

Use validation attributes on the bound property:

[Required(ErrorMessage = "Choose a delivery method.")]
public Delivery? DeliveryMethod { get; set; }

This preview is rendered with an empty selection and a seeded ModelState error. Its partial is rendered with the PartialModel prefix, so the error uses the full field name:

ModelState.AddModelError("PartialModel.DeliveryMethod", "Choose a delivery method.");

For an unbound group, use error to display a group error.

AccessibilityCopy Anchor Link

The group renders a fieldset and legend with native radio inputs and associated labels. Descriptions and validation messages are associated with the inputs. Set disabled="true" on the group or an item to disable it. Avoid interactive elements inside item labels. Media sits inside the label, so keep it decorative: an avatar without a name and an image with an empty alt leave the option text as its name.

API ReferenceCopy Anchor Link

<sa-radio-group>Copy Anchor Link

<sa-radio-group-item>Copy Anchor Link

<sa-radio-group-item-media>Copy Anchor Link

Media shown with an option, placed inside <sa-radio-group-item>. It renders no element of its own and takes no attributes; its content is placed in the option.