Radio Group

<pc-radio-group>

0.3.0

experimental

Radio groups are used to group multiple radios so they function as a single form control.

<pc-radio-group label="Select an option" name="group-1" value="option-1">
    <pc-radio value="option-1">Option 1</pc-radio>
    <pc-radio value="option-2">Option 2</pc-radio>
    <pc-radio value="option-3">Option 3</pc-radio>
</pc-radio-group>

Code

Edit

Demos

Hints

Add a descriptive hint to a radio group with the hint attribute. For hints that contain HTML, use the hint slot instead.

<pc-radio-group
    label="Select an option"
    hint="Select an option that makes you proud."
    name="group-1"
    value="option-1"
>
    <pc-radio value="option-1">Option 1</pc-radio>
    <pc-radio value="option-2">Option 2</pc-radio>
    <pc-radio value="option-3">Option 3</pc-radio>
</pc-radio-group>

Code

Edit

Disabling radios

Radios can be disabled by adding the disabled attribute to the respective options inside the radio group.

<pc-radio-group label="Select an option" name="group-1" value="option-1">
    <pc-radio value="option-1">Option 1</pc-radio>
    <pc-radio value="option-2" disabled>Option 2</pc-radio>
    <pc-radio value="option-3">Option 3</pc-radio>
</pc-radio-group>

Code

Edit

Size

The size of radios will be determined by the radio group’s size attribute.

<pc-radio-group
    class="radio-group-size"
    size="medium"
    label="Select an option"
    value="medium"
>
    <pc-radio value="small">Small</pc-radio>
    <pc-radio value="medium">Medium</pc-radio>
    <pc-radio value="large">Large</pc-radio>
</pc-radio-group>

<script>
    const radioGroup = document.querySelector(".radio-group-size");

    radioGroup.addEventListener("pc-change", () => {
        radioGroup.size = radioGroup.value;
    });
</script>

Code

Edit

Radios also have a size attribute. This can be useful in certain situations, but it will be ignored when used inside of a radio group.

Required

Set the required attribute to make selecting an option mandatory. If a value hasn’t been selected, it will prevent the form from submitting and display an error message.

<form class="radio-group-required">
    <pc-radio-group label="Select an option" name="group-1" required>
        <pc-radio value="option-1">Option 1</pc-radio>
        <pc-radio value="option-2">Option 2</pc-radio>
        <pc-radio value="option-3">Option 3</pc-radio>
    </pc-radio-group>
    <br />
    <pc-button appearance="primary" type="submit">Submit</pc-button>
    <pc-button appearance="neutral" type="reset">Reset</pc-button>
</form>

<script>
    const form = document.querySelector(".radio-group-required");

    form.addEventListener("submit", (event) => {
        event.preventDefault();
        alert("All fields are valid!");
    });
</script>

Code

Edit

Custom validity

Use the setCustomValidity() method to set a custom validation message. This will prevent the form from submitting and make the browser display the error message you provide. If you want to restore the default validation message, pass an empty string to the setCustomValidity() method.

<form class="radio-group-custom-validity">
    <pc-radio-group label="Select an option" name="group-1" value="option-1">
        <pc-radio value="not-me">Not me</pc-radio>
        <pc-radio value="me-neither">Me neither</pc-radio>
        <pc-radio value="select-me">Select me</pc-radio>
    </pc-radio-group>
    <br />
    <pc-button appearance="primary" type="submit">Submit</pc-button>
</form>

<script>
    const form = document.querySelector(".radio-group-custom-validity");
    const radioGroup = form.querySelector("pc-radio-group");
    const errorMessage = "You must select the last option.";

    customElements.whenDefined("pc-radio").then(() => {
        radioGroup.setCustomValidity(errorMessage);
    });

    form.addEventListener("pc-change", () => {
        const isValid = radioGroup.value === "select-me";
        radioGroup.setCustomValidity(isValid ? "" : errorMessage);
    });

    form.addEventListener("submit", (event) => {
        event.preventDefault();
        alert("All fields are valid!");
    });
</script>

Code

Edit

Properties

Name	Description	Default
`label`	The radio group’s label. This is required for proper accessibility. If you need to display HTML, use the `label` slot instead. Type: `string`	`""`
`hint`	The radio group’s hint. This is required for proper accessibility. If you need to display HTML, use the `hint` slot instead. Type: `string`	`""`
`name`	The name of the radio group, submitted as a name/value pair with form data. Type: `string`	`"option"`
`value`	The current value of the radio group, submitted as a name/value pair with form data. Type: `string`	`""`
`size`	The radio group’s size. This size will be applied to all child radios. Type: `"small" \| "medium" \| "large"`	`"medium"`
`form`	By default, form controls are associated with the nearest containing `<form>` element. This attribute allows you to place the form control outside of a form and associate it with the form that has this `id`. The form must be in the same document or shadow root for this to work. Type: `string`	`""`
`required`	Indicates if an option of the radio group must be chosen or not. Type: `boolean`	`false`
`validity`	Gets the validity state object.	‐
`validationMessage`	Gets the validation message.	‐
`updateComplete`	A read‐only promise that resolves when the component has finished updating.	‐

Learn more about customising animations.

Slots

Name	Description
(default)	The default slot where `<pc-radio>` elements are placed.
`label`	The radio group’s label. This is required for proper accessibility. Alternatively, you can use the `label` attribute.
`hint`	Text that describes how to use the radio group. Alternatively, you can use the `hint` attribute.

Learn more about using slots.

Methods

Name	Description	Arguments
`checkValidity()`	Checks for validity but does not show a validation message. Returns `true` when valid and `false` when invalid.	‐
`getForm()`	Gets the associated form, if one exists.	‐
`reportValidity()`	Checks for validity and shows the browser’s validation message if the radio group is invalid.	‐
`setCustomValidity()`	Sets a custom validation message. Pass an empty string to restore validity.	`message: string`
`focus()`	Sets focus on the radio group.	`options: FocusOptions`

Learn more about methods.

Events

Name	Description	Event detail
`pc-change`	Emitted when the radio group’s selected value changes.	‐
`pc-input`	Emitted when the radio group receives user input.	‐
`pc-invalid`	Emitted when the form control has been checked for validity and its constraints aren’t satisfied.	‐

Learn more about events.

Parts

Name	Description
`form-control`	The form control that wraps the label, input and hint.
`label`	The radio group’s label.
`input`	The radio group.
`hint`	The radio group’s hint.

Learn more about customising CSS parts.

Importing

If you’re using the autoloader or the standard loader, you can skip this section. But if you’re cherry picking, you can use any of the following snippets to import this component.

CDN (script tag)

CDN (import)

npm (import)

To manually import this component from the CDN, copy this code snippet and paste it in your HTML.

  <script type="module" src="https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.3/cdn/components/radio-group/radio-group.js"></script> 

To manually import this component from the CDN, copy this code snippet and paste it in your JavaScript file.

  import "https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.3/cdn/components/radio-group/radio-group.js"; 

To manually import this component from npm, copy this code snippet and paste it in your JavaScript file.

import "placer-toolkit/dist/components/radio-group/radio-group.js";