IconButton

Guidelines React

Github Storybook Markdown Copy for LLM

Icon Buttons are clickable icon elements that are used to trigger actions.

Import

import { IconButton } from "@cfa/react-core";

Live Editor

Events

Event Handlers

Use onPress instead of onClick.

The IconButton is built with the onPress prop, similar to onClick, but supports all user interactions via mouse, keyboard, and touch. The onPressStart, onPressEnd, and onPressChange events are triggered when a user presses, releases, or changes the state of the IconButton.

These handlers receive a PressEvent with information on type of event and the target.

PressEvent Props

Property	Type	Description
type	'pressstart' | 'pressend' | 'pressup' | 'press'	The type of press event being fired.
pointerType	PointerType	The pointer type that triggered the press event.
target	Element	The target element of the press event.
shiftKey	boolean	Whether the shift keyboard modifier was held during the press event.
ctrlKey	boolean	Whether the ctrl keyboard modifier was held during the press event.
metaKey	boolean	Whether the meta keyboard modifier was held during the press event.
altKey	boolean	Whether the alt keyboard modifier was held during the press event.
x	number	X position relative to the target.
y	number	Y position relative to the target.

PressEvent Methods

Method	Description
continuePropagation(): void	By default, press events stop propagation to parent elements. In cases where a handler decides not to handle a specific event, it can allow propagation.

Examples

Color

The color prop is defaulted to color="gray", with these additional options: "primary" | "secondary" | "white".

For an Icon Button used on a dark background, use color="white".

Disabled

For a disabled IconButton, use the isDisabled prop.

Size

The size prop allows for five sizes: "xs" | "sm" | "md" | "lg" | "xl"

Props

Visit the Documentation Site for the full list of props.

IconButton

Name	Type	Default	Description
children	React.ReactElement	-	The children of the component. A function may be provided to alter the children based on component state.
color	"gray" | "primary" | "secondary" | "white"	gray	-
ref	React.Ref<HTMLButtonElement>	-	Requires React 19
size	"xs" | "sm" | "md" | "lg" | "xl"	md	-
aria-controls	string	-	Identifies the element (or elements) whose contents or presence are controlled by the current element.
aria-current	boolean | "true" | "false" | "page" | "step" | "location" | "date" | "time"	-	Indicates whether this element represents the current item within a container or set of related elements.
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.
className	ClassNameOrFunction<ButtonRenderProps>	'react-aria-Button'	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.
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.
form	string	-	The `<form>` element to associate the button with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/button#form).
formAction	string | ((formData: FormData) => void | Promise<void>)	-	The URL that processes the information submitted by the button. Overrides the action attribute of the button's form owner.
formEncType	string	-	Indicates how to encode the form data that is submitted.
formMethod	string	-	Indicates the HTTP method used to submit the form.
formNoValidate	boolean	-	Indicates that the form is not to be validated when it is submitted.
formTarget	string	-	Overrides the target attribute of the button's form owner.
hidden	boolean	-	-
id	string	-	The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id).
inert	boolean	-	-
isDisabled	boolean	-	Whether the button is disabled.
isPending	boolean	-	Whether the button is in a pending state. This disables press and hover events while retaining focusability, and announces the pending state to screen readers.
lang	string	-	-
name	string	-	Submitted as a pair with the button's value as part of the form data.
onAnimationEnd	AnimationEventHandler<HTMLButtonElement>	-	-
onAnimationEndCapture	AnimationEventHandler<HTMLButtonElement>	-	-
onAnimationIteration	AnimationEventHandler<HTMLButtonElement>	-	-
onAnimationIterationCapture	AnimationEventHandler<HTMLButtonElement>	-	-
onAnimationStart	AnimationEventHandler<HTMLButtonElement>	-	-
onAnimationStartCapture	AnimationEventHandler<HTMLButtonElement>	-	-
onAuxClick	MouseEventHandler<HTMLButtonElement>	-	-
onAuxClickCapture	MouseEventHandler<HTMLButtonElement>	-	-
onBlur	(e: FocusEvent<Element, Element>) => void	-	Handler that is called when the element loses focus.
onClickCapture	MouseEventHandler<HTMLButtonElement>	-	-
onContextMenu	MouseEventHandler<HTMLButtonElement>	-	-
onContextMenuCapture	MouseEventHandler<HTMLButtonElement>	-	-
onDoubleClick	MouseEventHandler<HTMLButtonElement>	-	-
onDoubleClickCapture	MouseEventHandler<HTMLButtonElement>	-	-
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<HTMLButtonElement>	-	-
onGotPointerCaptureCapture	PointerEventHandler<HTMLButtonElement>	-	-
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<HTMLButtonElement>	-	-
onLostPointerCaptureCapture	PointerEventHandler<HTMLButtonElement>	-	-
onMouseDown	MouseEventHandler<HTMLButtonElement>	-	-
onMouseDownCapture	MouseEventHandler<HTMLButtonElement>	-	-
onMouseEnter	MouseEventHandler<HTMLButtonElement>	-	-
onMouseLeave	MouseEventHandler<HTMLButtonElement>	-	-
onMouseMove	MouseEventHandler<HTMLButtonElement>	-	-
onMouseMoveCapture	MouseEventHandler<HTMLButtonElement>	-	-
onMouseOut	MouseEventHandler<HTMLButtonElement>	-	-
onMouseOutCapture	MouseEventHandler<HTMLButtonElement>	-	-
onMouseOver	MouseEventHandler<HTMLButtonElement>	-	-
onMouseOverCapture	MouseEventHandler<HTMLButtonElement>	-	-
onMouseUp	MouseEventHandler<HTMLButtonElement>	-	-
onMouseUpCapture	MouseEventHandler<HTMLButtonElement>	-	-
onPointerCancel	PointerEventHandler<HTMLButtonElement>	-	-
onPointerCancelCapture	PointerEventHandler<HTMLButtonElement>	-	-
onPointerDown	PointerEventHandler<HTMLButtonElement>	-	-
onPointerDownCapture	PointerEventHandler<HTMLButtonElement>	-	-
onPointerEnter	PointerEventHandler<HTMLButtonElement>	-	-
onPointerLeave	PointerEventHandler<HTMLButtonElement>	-	-
onPointerMove	PointerEventHandler<HTMLButtonElement>	-	-
onPointerMoveCapture	PointerEventHandler<HTMLButtonElement>	-	-
onPointerOut	PointerEventHandler<HTMLButtonElement>	-	-
onPointerOutCapture	PointerEventHandler<HTMLButtonElement>	-	-
onPointerOver	PointerEventHandler<HTMLButtonElement>	-	-
onPointerOverCapture	PointerEventHandler<HTMLButtonElement>	-	-
onPointerUp	PointerEventHandler<HTMLButtonElement>	-	-
onPointerUpCapture	PointerEventHandler<HTMLButtonElement>	-	-
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<HTMLButtonElement>	-	-
onScrollCapture	UIEventHandler<HTMLButtonElement>	-	-
onTouchCancel	TouchEventHandler<HTMLButtonElement>	-	-
onTouchCancelCapture	TouchEventHandler<HTMLButtonElement>	-	-
onTouchEnd	TouchEventHandler<HTMLButtonElement>	-	-
onTouchEndCapture	TouchEventHandler<HTMLButtonElement>	-	-
onTouchMove	TouchEventHandler<HTMLButtonElement>	-	-
onTouchMoveCapture	TouchEventHandler<HTMLButtonElement>	-	-
onTouchStart	TouchEventHandler<HTMLButtonElement>	-	-
onTouchStartCapture	TouchEventHandler<HTMLButtonElement>	-	-
onTransitionCancel	TransitionEventHandler<HTMLButtonElement>	-	-
onTransitionCancelCapture	TransitionEventHandler<HTMLButtonElement>	-	-
onTransitionEnd	TransitionEventHandler<HTMLButtonElement>	-	-
onTransitionEndCapture	TransitionEventHandler<HTMLButtonElement>	-	-
onTransitionRun	TransitionEventHandler<HTMLButtonElement>	-	-
onTransitionRunCapture	TransitionEventHandler<HTMLButtonElement>	-	-
onTransitionStart	TransitionEventHandler<HTMLButtonElement>	-	-
onTransitionStartCapture	TransitionEventHandler<HTMLButtonElement>	-	-
onWheel	WheelEventHandler<HTMLButtonElement>	-	-
onWheelCapture	WheelEventHandler<HTMLButtonElement>	-	-
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", ButtonRenderProps>	-	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<ButtonRenderProps>	-	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"	-	-
type	"button" | "submit" | "reset"	'button'	The behavior of the button when used in an HTML form.
value	string	-	The value associated with the button's name when it's submitted with the form data.