ToggleButton

ToggleButton is used to select a boolean value using a button.

Import #


import { ToggleButtonModule } from 'primeng/togglebutton';

Basic #

Two-way binding to a boolean property is defined using the standard ngModel directive.

Off


<p-toggleButton 
    [(ngModel)]="checked" 
    onLabel="On" 
    offLabel="Off" />

Reactive Forms #

ToggleButton can also be used with reactive forms. In this case, the formControlName property is used to bind the component to a form control.


<form [formGroup]="formGroup">
    <p-toggleButton 
        formControlName="checked" 
        onLabel="On" 
        offLabel="Off" />
</form>

Customized #

Icons and Labels can be customized using onLabel, offLabel, onIcon and offIcon properties.

Unlocked


<p-toggleButton 
    [(ngModel)]="checked" 
    onLabel="Locked" 
    offLabel="Unlocked" 
    onIcon="pi pi-check" 
    offIcon="pi pi-times" 
    onIcon="pi pi-lock" 
    offIcon="pi pi-lock-open" 
    styleClass="w-9rem"
    ariaLabel="Do you confirm" />

Disabled #

When disabled is present, the element cannot be edited and focused.


<p-toggleButton
    disabled="true" 
    onIcon="pi pi-check" 
    offIcon="pi pi-times" 
    [(ngModel)]="checked" 
    onLabel="Yes"
    offLabel="No" 
    styleClass="w-full sm:w-10rem" 
    ariaLabel="Confirmation" />

Style #

Following is the list of structural style classes, for theming classes visit theming page.

Name	Element
p-togglebutton	Container element.
p-button-icon-left	Text element.
p-button-icon-right	Value element.

Accessibility #

Screen Reader

ToggleButton component uses an element with button role and updates aria-pressed state for screen readers. Value to describe the component can be defined with ariaLabelledBy or ariaLabel props, it is highly suggested to use either of these props as the component changes the label displayed which will result in screen readers to read different labels when the component receives focus. To prevent this, always provide an aria label that does not change related to state.


<span id="rememberme">Remember Me</span>
<p-toggleButton ariaLabelledBy="rememberme" />

<p-toggleButton ariaLabel="Remember Me" />

Keyboard Support

Key	Function
tab	Moves focus to the button.
space	Toggles the checked state.

ToggleButton API

API defines helper props, events and others for the PrimeNG ToggleButton module.

ToggleButton #

ToggleButton is used to select a boolean value using a button.

Properties #

Defines the input properties of the component.

name	type	default	description
onLabel	string	null	Label for the on state.
offLabel	string	null	Label for the off state.
onIcon	string	null	Icon for the on state.
offIcon	string	null	Icon for the off state.
ariaLabel	string	null	Defines a string that labels the input for accessibility.
ariaLabelledBy	string	null	Establishes relationships between the component and label(s) where its value should be one or more element IDs.
disabled	boolean	false	When present, it specifies that the element should be disabled.
style	any	null	Inline style of the element.
styleClass	string	null	Style class of the element.
inputId	string	null	Identifier of the focus input to match a label defined for the component.
tabindex	number	0	Index of the element in tabbing order.
iconPos	"left" \| "right"	left	Position of the icon.
autofocus	boolean	false	When present, it specifies that the component should automatically get focus on load.

Emitters #

Defines emit that determine the behavior of the component based on a given condition or report the actions that the component takes.

name	parameters	description
onChange	event : ToggleButtonChangeEvent	Callback to invoke on value change.

Templates #

Defines the templates used by the component.

name	parameters	description
icon	context : { $implicit: boolean, // Checked. }	Custom icon template.

Events #

Defines the custom events used by the component's emitters.

ToggleButtonChangeEvent #

Custom change event.

name	type	description
originalEvent	Event	Browser event.
checked	boolean	Boolean value to represent checked state.