Skip to content

ptcs-radio

Visual

A radio button consists of a button and a text label.

You can assign a maximum width to the radio button label to display it across multiple lines.

Overview

A radio button can be in an on or an off state. When the radio button is checked, it is set to on. Multiple radio buttons can belong to the same group. Only one button in the group can be in an on state.

A radio button can be in a selected and/or a disabled state. A disabled button does not respond to UI events.

A radio button has a radiogroup association to support the group notion. When checked (selected), the radio button remains in that on state until another radio button in the same radiogroup is checked. The radio button cannot be deselected like toggle buttons.

Usage Examples

Basic Usage

<ptcs-radio radiogroup="groupname" label="This is the label string"></ptcs-radio>

Start in on state (checked)

<ptcs-radio radiogroup="mammal" label="Dog" checked></ptcs-radio>

NOTE: By default, the first radio button of a radiogroup is checked. In the web component, this happens in the demo HTML, and for ptcs-radio that have an empty radiogroup. In the wrapped Radio Button of Composer, this functionality is triggered when the radiogroup is changed. In Mashup Builder, when you initially drag the Radio Button widget, none of them are checked. The first occurrence of a new and non-empty radiogroup definition checks the button.

A group of radio buttons

<ptcs-radio radiogroup="animal" label="Cat"></ptcs-radio>
<ptcs-radio radiogroup="animal" label="Dog"></ptcs-radio>
<ptcs-radio radiogroup="animal" label="Parrot"></ptcs-radio>

Radio buttons within the same radiogroup are mutually exclusive. Only one of the buttons in same radiogroup can be in the on state.

A radio button with maximum width label

    <ptcs-radio radiogroup="reptile" label="Anaconda. A very long label might be displayed as multiline, and does not get truncated or an ellipsis" label-max-width="150px">

By default, the radio button label is a single line. You can wrap the label text across multiple lines by specifying a maximum width for the label or its inherited width.

Component API

Properties

Property Type Description Default Triggers a changed event?
checked Boolean The current state (on: checked === true, off: checked === false) false No
disabled Boolean Disables the component. Users cannot interact with the element. false No
label String The string for the radio button label "Radio Button" No
labelMaxWidth String The maximum width (a CSS length) of the radio button label "" No
preventAutoSelect Boolean The radio button normally auto-selects itself when connected to the DOM if no other radio button is selected in the current radiogroup. Property preventAutoSelect disables this behavior. No
radiogroup String To support mutually exclusive radio buttons in same radiogroup "" No
tooltip String The tooltip that appears when hovering over the radio button "" No
tooltipIcon String The icon for the tooltip "" No
extraValidation Function Custom validation function to complement the component's client-side validation logic. This is invoked with the radio button component itself as parameter, so that it can use any radio button property for custom validation. Can return true (= valid), false (= invalid), or undefined (ignore validation) No
externalValidity String Radio button validity as determined externally (server-side). Value: undefined, "unvalidated", "invalid", or "valid" No
hideValidationCriteria Boolean Don't show validation criteria in unvalidated state? No
hideValidationError Boolean Don't show validation error state? No
hideValidationSuccess Boolean Don't show validation success state? No
required Boolean Validation criterion: Must the radio button be checked? false No
validationCriteria String The validation details message No
validationCriteriaIcon String Icon for criteria state (unvalidated). "cds:icon_info:" No
validationErrorIcon String Icon for error state (invalid). "cds:icon_error" No
validationMessage String The validation (title) message No
validationSuccessDetails String The validation success details message No
validationSuccessIcon String Icon for success state (valid). "cds:icon_success" No
validationSuccessMessage String The validation success (title) message. "Success" No

Parts Structure

The radio button exposes following parts from its shadow tree for styling purposes.

Part Name Description
root The radio button parent element
circle The radio button
exterior-ring The exterior ring of the radio button
interior-button The interior part of the radio button, that is filled when the button is checked
label The radio button label

Events

Name Data Description
checked-changed {checked} Generated when the state of the radio button changes

Methods

No methods

State attributes

Attribute Description Part
checked The current state :host, root
disabled Indicates whether the radio button is disabled :host, root
label The displayed label :host, label
radiogroup The associated radio group :host