Radio Component

Component Status

| Component | Status | | ---------- | ----------------------------------------------------------- | | Radio | | | RadioGroup | |

Single-select radio button components for Phila UI. Use Radio for a standalone radio button, or RadioGroup to manage a set of related options with a shared label, description, and error state.

Installation

pnpm add @phila/phila-ui-radio @phila/phila-ui-core
# or
npm install @phila/phila-ui-radio @phila/phila-ui-core

Import core styles in your main entry file (e.g., main.js|ts):

import "@phila/phila-ui-core/styles/template-light.css";

Usage

RadioGroup (recommended)

RadioGroup's modelValue is a map of choice value → selected (exactly one true), not the selected value itself — every choice gets a key, mirroring CheckboxGroup's shape:

<script setup lang="ts">
import { RadioGroup } from "@phila/phila-ui-radio";
import { ref } from "vue";

const modelValue = ref<Record<string, boolean>>({});
const choices = [
  { text: "Option A", value: "a" },
  { text: "Option B", value: "b" },
  { text: "Option C", value: "c", tooltip: "Extra context about Option C shown on hover." },
];
</script>

<template>
  <RadioGroup groupLabel="Choose an option" description="Select exactly one." :choices="choices" v-model="modelValue" />
</template>

Radio (standalone)

Standalone Radio's modelValue is the selected value itself (a plain string), unlike RadioGroup's map:

<script setup lang="ts">
import { Radio } from "@phila/phila-ui-radio";
import { ref } from "vue";

const selected = ref("");
</script>

<template>
  <Radio name="group" value="a" text="Option A" v-model="selected" />
  <Radio name="group" value="b" text="Option B" v-model="selected" />
</template>

Tooltip

<Radio name="group" value="a" text="Option with help" tooltip="Extra context shown on hover." v-model="selected" />

Radio Props

| Prop | Type | Default | Description | | ------------ | --------- | ------- | ------------------------------------------------------------------------ | | text | string | — | Label text displayed next to the radio button | | value | string | — | The value submitted when this radio is selected | | name | string | — | Groups radio buttons together (use the same name for mutual exclusivity) | | modelValue | string | — | Currently selected value (use with v-model); compared against value | | disabled | boolean | false | Disables the radio button | | error | boolean | false | Applies error styling | | tooltip | string | — | Shows an info icon next to the label that reveals this text on hover | | className | string | — | Additional CSS classes |

RadioGroup Props

| Prop | Type | Default | Description | | -------------- | ------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------- | | groupLabel | string | — | Label displayed above the group | | description | string | — | Optional helper text below the label | | choices | { text: string, value: string, disabled?: boolean, tooltip?: string }[] | — | Array of options to render | | modelValue | Record<string, boolean> | — | Map of choice value → selected; exactly one true (use with v-model) | | error | boolean | false | Applies error styling to the group | | errorMessage | string | — | Error message shown below the options when error is true | | disabled | boolean | false | Disables all radio buttons in the group | | className | string | — | Additional CSS classes |

Events

Radio

| Event | Payload | Description | | ------------------- | -------- | ---------------------------------- | | update:modelValue | string | Emitted when the radio is selected |

RadioGroup

| Event | Payload | Description | | ------------------- | ------------------------- | ------------------------------------------------------------------ | | update:modelValue | Record<string, boolean> | Emitted with the full updated map when the selected option changes |

Visual States

| State | Description | | -------- | ---------------------------------------- | | Default | Gray border, white background | | Hover | Primary-colored border (2px) | | Selected | Primary fill with white center dot | | Focus | Primary-colored outline around the label | | Error | Error-colored border (2px) | | Disabled | Muted border and text, not interactive |

Development

Install Dependencies

pnpm install

Run Demo

pnpm dev

Run lint

pnpm lint

Create Production Build

pnpm build

Publishing to NPM

Follow the release instructions using changesets.

License

MIT