Components / Radio

Radio

# Introduction

Use radio buttons when you need users to select only one option from a small set of mutually exclusive choices. They are best for clear, concise options that don’t require scrolling or searching. Unlike dropdowns, radio buttons make all choices visible at once, reducing the need for interaction.

Select, on the other hand, is better suited for situations with many options or when saving screen space is a priority, as it hides choices in a dropdown menu.

# Usage

The Radio component needs <zinq:radio.option> elements to define the options.

Each <zinq:radio.option> element should contain the text that will be displayed to the user and value attribute to define the value of the option.

  
<zinq:radio>
    <zinq:radio.option value="beginner">Beginner</zinq:form.option>
    <zinq:radio.option value="intermediate">Intermediate</zinq:form.option>
    <zinq:radio.option value="advanced">Advanced</zinq:form.option>
</zinq:radio>

# Customization

The Radio component can be customized in many ways.

# Label

Like many other form components, the Radio component can have a label. You can set the label by using the label attribute.

  
<zinq:radio label="Choose your course difficulty">
    <zinq:radio.option value="beginner">Beginner</zinq:form.option>
    <zinq:radio.option value="intermediate">Intermediate</zinq:form.option>
    <zinq:radio.option value="advanced">Advanced</zinq:form.option>
</zinq:radio>

# Sizing

The Radio component comes in three sizes: default , sm , and lg . By default, the size is default .

  
<div class="flex flex-col space-y-6">
    <zinq:radio size="sm">
        <zinq:radio.option value="beginner">Beginner</zinq:form.option>
        <zinq:radio.option value="intermediate">Intermediate</zinq:form.option>
        <zinq:radio.option value="advanced">Advanced</zinq:form.option>
    </zinq:radio>
    <zinq:radio>
        <zinq:radio.option value="beginner">Beginner</zinq:form.option>
        <zinq:radio.option value="intermediate">Intermediate</zinq:form.option>
        <zinq:radio.option value="advanced">Advanced</zinq:form.option>
    </zinq:radio>
    <zinq:radio size="lg">
        <zinq:radio.option value="beginner">Beginner</zinq:form.option>
        <zinq:radio.option value="intermediate">Intermediate</zinq:form.option>
        <zinq:radio.option value="advanced">Advanced</zinq:form.option>
    </zinq:radio>
</div>

# Inline

Place radio buttons on the same line by adding the inline attribute to the <zinq:radio> component.

  
<zinq:radio inline>
    <zinq:radio.option value="beginner">Beginner</zinq:form.option>
    <zinq:radio.option value="intermediate">Intermediate</zinq:form.option>
    <zinq:radio.option value="advanced">Advanced</zinq:form.option>
</zinq:radio>

# Controlled

The Radio component state can be changed from any other component. You can simply use Alpine's @click directive to toggle the state.

Just define an id for the radio and use the Alpine.store to change the state.

I know a little bit
  
<zinq:radio id="my-radio-id">
    <zinq:radio.option value="beginner">Beginner</zinq:form.option>
    <zinq:radio.option value="intermediate">Intermediate</zinq:form.option>
    <zinq:radio.option value="advanced">Advanced</zinq:form.option>
</zinq:radio>
<div class="mt-4">
    <zinq:badge
        @click="Alpine.store('zinq_radio')['my-radio-id'].value = 'intermediate'"
        class="cursor-pointer select-none"
    >I know a little bit</zinq:badge>
</div>

# Default value

You can set the default value of the radio group by setting the value attribute on the zinq:form.radio-group component.

  
<zinq:radio value="intermediate">
    <zinq:radio.option value="beginner">Beginner</zinq:form.option>
    <zinq:radio.option value="intermediate">Intermediate</zinq:form.option>
    <zinq:radio.option value="advanced">Advanced</zinq:form.option>
</zinq:radio>

# Livewire

You can use the wire:model directive to bind the Radio to a Livewire property.

  
<zinq:radio wire:model="difficulty">
    ...
</zinq:radio>

# Live

You can also use wire:model.live to update the model on every change.

Course difficulty: beginner

  
public string $difficulty = '';

public function render(): string
{
    return <<<HTML
        <div>
            <p>Course difficulty: {$this->difficulty}</p>
            <zinq:radio wire:model.live="difficulty">
                <zinq:radio.option value="beginner">Beginner</zinq:form.option>
                <zinq:radio.option value="intermediate">Intermediate</zinq:form.option>
                <zinq:radio.option value="advanced">Advanced</zinq:form.option>
            </zinq:radio>
        </div>
    HTML;
}

# Validation errors

The Radio component will automatically display validation errors for you when wire:model attribute is used.

  
#[Rule('required')]
public string $difficulty = '';

public function save(): void
{
    $this->validate();
}

public function render(): string
{
    return <<<HTML
        <zinq:form action="save">
            <zinq:radio wire:model="difficulty">
                <zinq:radio.option value="beginner">Beginner</zinq:form.option>
                <zinq:radio.option value="intermediate">Intermediate</zinq:form.option>
                <zinq:radio.option value="advanced">Advanced</zinq:form.option>
            </zinq:radio>
            <zinq:button>Save to see validation error</zinq:button>
        </zinq:form>
    HTML;
}

# Manual validation errors

Or you can manually display validation errors by using the error attribute.

We do not offer pro difficulty yet!
  
<zinq:radio error="We do not offer pro difficulty yet!">
    <zinq:radio.option value="beginner">Beginner</zinq:form.option>
    <zinq:radio.option value="intermediate">Intermediate</zinq:form.option>
    <zinq:radio.option value="advanced">Advanced</zinq:form.option>
</zinq:radio>