ToggleButton

Guidelines React

Github Storybook Markdown Copy for LLM

The ToggleButton component is a button that can be toggled on or off. It is used to represent a binary choice. It can be used singularly or within a ToggleButtonGroup.

Import

import { ToggleButton, ToggleButtonGroup } from "@cfa/react-core";

Live Editor

Examples: Single

Events

ToggleButton supports all user interactions via mouse, keyboard, and touch events with the onPress prop. This is similar to the onClick event, but not limited to mouse events. In addition, the onPressStart, onPressEnd, and onPressChange events are also supported. These events are triggered when the user presses, releases, or changes the state of the button.

Autofocus

The autoFocus prop allows the ToggleButton to receive focus when the page loads.

Default Selected

The defaultSelected prop sets the initial selected state of the ToggleButton.

Disabled

The isDisabled prop disables the ToggleButton, preventing user interaction.

Controlled

The isSelected prop sets the selected state of the ToggleButton, helpful when controlled by state.

Size

The size prop sets the size of the ToggleButton. Available sizes are sm, md, and lg.

Examples: Group

Default

Controlled

Disabled

You can set a single ToggleButton or the entire ToggleButtonGroup to disabled via the isDisabled prop.

Full Width

Use the fullWidth prop to have the ToggleButtonGroup span the entire width available.

Orientation

Set the orientation prop to one of the following options: "horizontal" by default, or "vertical".

Selection Mode

The selectionMode prop allows for "single" | "multiple". A "single" selection within a ToggleButtonGroup requires the Group’s children to have unique id’s.

Separators

ToggleButtonGroup are separated by dividers by default. To hide the dividers set the noSeparators prop.

Props

Visit the Documentation Site for the full list of props.

ToggleButton

Name	Type	Default	Description
size	"sm" | "md" | "lg"	md	Size of the ToggleButton.
variant	"icon" | "text"	icon	Icon variant is icon only where text accepts a string and icon.
aria-controls	string	-	Identifies the element (or elements) whose contents or presence are controlled by the current element.
aria-describedby	string	-	Identifies the element (or elements) that describes the object.
aria-details	string	-	Identifies the element (or elements) that provide a detailed, extended description for the object.
aria-disabled	boolean | "true" | "false"	-	Indicates whether the element is disabled to users of assistive technology.
aria-expanded	boolean | "true" | "false"	-	Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed.
aria-haspopup	boolean | "true" | "false" | "menu" | "listbox" | "tree" | "grid" | "dialog"	-	Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element.
aria-label	string	-	Defines a string value that labels the current element.
aria-labelledby	string	-	Identifies the element (or elements) that labels the current element.
aria-pressed	boolean | "true" | "false" | "mixed"	-	Indicates the current "pressed" state of toggle buttons.
autoFocus	boolean	-	Whether the element should receive focus on render.
children	ChildrenOrFunction<ToggleButtonRenderProps>	-	The children of the component. A function may be provided to alter the children based on component state.
className	ClassNameOrFunction<ToggleButtonRenderProps>	'react-aria-ToggleButton'	The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state.
defaultSelected	boolean	-	Whether the element should be selected (uncontrolled).
dir	string	-	-
excludeFromTabOrder	boolean	-	Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.
hidden	boolean	-	-
id	Key	-	When used in a ToggleButtonGroup, an identifier for the item in `selectedKeys`. When used standalone, a DOM id.
inert	boolean	-	-
isDisabled	boolean	-	Whether the button is disabled.
isSelected	boolean	-	Whether the element should be selected (controlled).
lang	string	-	-
onAnimationEnd	AnimationEventHandler<HTMLDivElement>	-	-
onAnimationEndCapture	AnimationEventHandler<HTMLDivElement>	-	-
onAnimationIteration	AnimationEventHandler<HTMLDivElement>	-	-
onAnimationIterationCapture	AnimationEventHandler<HTMLDivElement>	-	-
onAnimationStart	AnimationEventHandler<HTMLDivElement>	-	-
onAnimationStartCapture	AnimationEventHandler<HTMLDivElement>	-	-
onAuxClick	MouseEventHandler<HTMLDivElement>	-	-
onAuxClickCapture	MouseEventHandler<HTMLDivElement>	-	-
onBlur	(e: FocusEvent<Element, Element>) => void	-	Handler that is called when the element loses focus.
onChange	(isSelected: boolean) => void	-	Handler that is called when the element's selection state changes.
onClickCapture	MouseEventHandler<HTMLDivElement>	-	-
onContextMenu	MouseEventHandler<HTMLDivElement>	-	-
onContextMenuCapture	MouseEventHandler<HTMLDivElement>	-	-
onDoubleClick	MouseEventHandler<HTMLDivElement>	-	-
onDoubleClickCapture	MouseEventHandler<HTMLDivElement>	-	-
onFocus	(e: FocusEvent<Element, Element>) => void	-	Handler that is called when the element receives focus.
onFocusChange	(isFocused: boolean) => void	-	Handler that is called when the element's focus status changes.
onGotPointerCapture	PointerEventHandler<HTMLDivElement>	-	-
onGotPointerCaptureCapture	PointerEventHandler<HTMLDivElement>	-	-
onHoverChange	(isHovering: boolean) => void	-	Handler that is called when the hover state changes.
onHoverEnd	(e: HoverEvent) => void	-	Handler that is called when a hover interaction ends.
onHoverStart	(e: HoverEvent) => void	-	Handler that is called when a hover interaction starts.
onKeyDown	(e: KeyboardEvent) => void	-	Handler that is called when a key is pressed.
onKeyUp	(e: KeyboardEvent) => void	-	Handler that is called when a key is released.
onLostPointerCapture	PointerEventHandler<HTMLDivElement>	-	-
onLostPointerCaptureCapture	PointerEventHandler<HTMLDivElement>	-	-
onMouseDown	MouseEventHandler<HTMLDivElement>	-	-
onMouseDownCapture	MouseEventHandler<HTMLDivElement>	-	-
onMouseEnter	MouseEventHandler<HTMLDivElement>	-	-
onMouseLeave	MouseEventHandler<HTMLDivElement>	-	-
onMouseMove	MouseEventHandler<HTMLDivElement>	-	-
onMouseMoveCapture	MouseEventHandler<HTMLDivElement>	-	-
onMouseOut	MouseEventHandler<HTMLDivElement>	-	-
onMouseOutCapture	MouseEventHandler<HTMLDivElement>	-	-
onMouseOver	MouseEventHandler<HTMLDivElement>	-	-
onMouseOverCapture	MouseEventHandler<HTMLDivElement>	-	-
onMouseUp	MouseEventHandler<HTMLDivElement>	-	-
onMouseUpCapture	MouseEventHandler<HTMLDivElement>	-	-
onPointerCancel	PointerEventHandler<HTMLDivElement>	-	-
onPointerCancelCapture	PointerEventHandler<HTMLDivElement>	-	-
onPointerDown	PointerEventHandler<HTMLDivElement>	-	-
onPointerDownCapture	PointerEventHandler<HTMLDivElement>	-	-
onPointerEnter	PointerEventHandler<HTMLDivElement>	-	-
onPointerLeave	PointerEventHandler<HTMLDivElement>	-	-
onPointerMove	PointerEventHandler<HTMLDivElement>	-	-
onPointerMoveCapture	PointerEventHandler<HTMLDivElement>	-	-
onPointerOut	PointerEventHandler<HTMLDivElement>	-	-
onPointerOutCapture	PointerEventHandler<HTMLDivElement>	-	-
onPointerOver	PointerEventHandler<HTMLDivElement>	-	-
onPointerOverCapture	PointerEventHandler<HTMLDivElement>	-	-
onPointerUp	PointerEventHandler<HTMLDivElement>	-	-
onPointerUpCapture	PointerEventHandler<HTMLDivElement>	-	-
onPress	(e: PressEvent) => void	-	Handler that is called when the press is released over the target.
onPressChange	(isPressed: boolean) => void	-	Handler that is called when the press state changes.
onPressEnd	(e: PressEvent) => void	-	Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target.
onPressStart	(e: PressEvent) => void	-	Handler that is called when a press interaction starts.
onPressUp	(e: PressEvent) => void	-	Handler that is called when a press is released over the target, regardless of whether it started on the target or not.
onScroll	UIEventHandler<HTMLDivElement>	-	-
onScrollCapture	UIEventHandler<HTMLDivElement>	-	-
onTouchCancel	TouchEventHandler<HTMLDivElement>	-	-
onTouchCancelCapture	TouchEventHandler<HTMLDivElement>	-	-
onTouchEnd	TouchEventHandler<HTMLDivElement>	-	-
onTouchEndCapture	TouchEventHandler<HTMLDivElement>	-	-
onTouchMove	TouchEventHandler<HTMLDivElement>	-	-
onTouchMoveCapture	TouchEventHandler<HTMLDivElement>	-	-
onTouchStart	TouchEventHandler<HTMLDivElement>	-	-
onTouchStartCapture	TouchEventHandler<HTMLDivElement>	-	-
onTransitionCancel	TransitionEventHandler<HTMLDivElement>	-	-
onTransitionCancelCapture	TransitionEventHandler<HTMLDivElement>	-	-
onTransitionEnd	TransitionEventHandler<HTMLDivElement>	-	-
onTransitionEndCapture	TransitionEventHandler<HTMLDivElement>	-	-
onTransitionRun	TransitionEventHandler<HTMLDivElement>	-	-
onTransitionRunCapture	TransitionEventHandler<HTMLDivElement>	-	-
onTransitionStart	TransitionEventHandler<HTMLDivElement>	-	-
onTransitionStartCapture	TransitionEventHandler<HTMLDivElement>	-	-
onWheel	WheelEventHandler<HTMLDivElement>	-	-
onWheelCapture	WheelEventHandler<HTMLDivElement>	-	-
preventFocusOnPress	boolean	-	Whether to prevent focus from moving to the button when pressing it. Caution, this can make the button inaccessible and should only be used when alternative keyboard interaction is provided, such as ComboBox's MenuTrigger or a NumberField's increment/decrement control.
render	DOMRenderFunction<"button", ToggleButtonRenderProps>	-	Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: * You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). * Only a single root DOM element can be rendered (no fragments). * You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.
slot	string	-	A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent.
style	StyleOrFunction<ToggleButtonRenderProps>	-	The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state.
translate	"yes" | "no"	-	-

ToggleButtonGroup