Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs: update Button and DropdownMenu docs for isIconOnly prop (#1261)

Cindy Zhangceb8c273cd91
diff --git a/packages/core/src/Button/Button.doc.mjs b/packages/core/src/Button/Button.doc.mjs
index d063e7d894..35e17c8fbe 100644
--- a/packages/core/src/Button/Button.doc.mjs
+++ b/packages/core/src/Button/Button.doc.mjs
@@ -23,7 +23,7 @@ export const docs = {
name: 'label',
type: 'string',
description:
- 'Accessible label; used as aria-label for icon-only buttons.',
+ 'Accessible label. Rendered as visible text by default; used as aria-label when isIconOnly is true.',
required: true,
},
{
@@ -75,19 +75,26 @@ export const docs = {
name: 'icon',
type: 'ReactNode',
description:
- 'Icon element. When provided without children the button renders as a square icon-only button.',
+ 'Icon element rendered before the label text.',
+ },
+ {
+ name: 'isIconOnly',
+ type: 'boolean',
+ description:
+ 'When true, renders as a square icon-only button with label as aria-label. Requires icon.',
+ default: 'false',
},
{
name: 'children',
type: 'ReactNode',
description:
- 'Button content. When provided alongside icon, the text is rendered next to the icon.',
+ 'Optional visible content. When provided, rendered instead of label as the visible text.',
},
{
name: 'endContent',
type: 'ReactElement<XDSIconProps> | ReactElement<XDSBadgeProps>',
description:
- 'Trailing icon or badge rendered after the label. Only accepts <XDSIcon> or <XDSBadge>. Ignored for icon-only buttons. Color is inherited from the button variant.',
+ 'Trailing icon or badge rendered after the label. Ignored when isIconOnly is true. Color is inherited from the button variant.',
},
{
name: 'tooltip',
@@ -127,16 +134,15 @@ export const docs = {
},
{
label: 'Icon-only button',
- code: `// Pass \`icon\` without \`children\` β€” \`label\` becomes the aria-label
-<XDSButton label="Settings" icon={<GearIcon />} variant="ghost" />`,
+ code: '<XDSButton label="Settings" icon={<GearIcon />} variant="ghost" isIconOnly />',
},
{
label: 'Icon-only with emoji content',
- code: '<XDSButton label="Select rocket emoji" icon={<span>πŸš€</span>} variant="ghost" size="sm" />',
+ code: '<XDSButton label="Select rocket emoji" icon={<span>πŸš€</span>} variant="ghost" size="sm" isIconOnly />',
},
{
label: 'Icon + visible label',
- code: '<XDSButton label="Edit" icon={<PencilIcon />}>Edit</XDSButton>',
+ code: '<XDSButton label="Edit" icon={<PencilIcon />} />',
},
{
label: 'endContent β€” badge after label',
@@ -144,19 +150,17 @@ export const docs = {
},
{
label: 'endContent β€” icon, label, and badge',
- code: '<XDSButton label="Edit" icon={<PencilIcon />} endContent={<XDSBadge label="New" />}>Edit</XDSButton>',
+ code: '<XDSButton label="Edit" icon={<PencilIcon />} endContent={<XDSBadge label="New" />} />',
},
{
label: 'endContent β€” settings with badge',
- code: `<XDSButton label="Settings" icon={<GearIcon />} endContent={<XDSBadge label="New" />}>
- Settings
-</XDSButton>`,
+ code: '<XDSButton label="Settings" icon={<GearIcon />} endContent={<XDSBadge label="New" />} />',
},
],
accessibility: [
'Renders a native <button> element for correct semantics and keyboard support',
- 'Icon-only buttons (icon without children) set aria-label from the label prop',
+ 'Icon-only buttons (isIconOnly={true}) set aria-label from the label prop',
'Loading state sets aria-busy and announces "Loading" via a role="status" live region',
'Content is hidden from assistive tech during loading via aria-hidden',
'When tooltip is present and button is disabled, uses aria-disabled instead of native disabled to keep the button focusable for keyboard tooltip access',
@@ -181,8 +185,8 @@ export const docs = {
'Hover/active states use backgroundImage with linear-gradient to layer overlay colors on top of the base background.',
'Destructive variant uses colorTokens.negative for its focus outline color.',
'endContent is wrapped in a <span> with color: inherit so icons/badges match the button text color across all variants.',
- 'When icon is provided without children, the button becomes icon-only: it renders as a perfect square (aspectRatio: 1/1), and label is used as aria-label (not rendered visually). Works with any ReactNode as the icon β€” SVG components, emoji, or text.',
- 'endContent is ignored for icon-only buttons (when icon is provided without children) to preserve the square aspect ratio.',
+ 'When isIconOnly is true, the button renders as a perfect square (aspectRatio: 1/1), and label is used as aria-label (not rendered visually). Works with any ReactNode as the icon β€” SVG components, emoji, or text.',
+ 'endContent is ignored when isIconOnly is true to preserve the square aspect ratio.',
'Prefer XDSButton over <div onClick> or <span onClick> for accessibility β€” it provides keyboard navigation, focus management, and screen reader support.',
'Icon-only buttons are suitable for toolbars, action grids, and compact controls.',
'onClick fires before onClickAction; calling preventDefault in onClick prevents onClickAction from running.',
@@ -434,7 +438,7 @@ export const docsDense = {
],
accessibility: [
'Native <button> for correct semantics + keyboard support.',
- 'Icon-only buttons set aria-label from label prop.',
+ 'Icon-only buttons (isIconOnly) set aria-label from label prop.',
'Loading sets aria-busy + announces via role="status" live region.',
'Content hidden from AT during loading via aria-hidden.',
'Tooltip+disabled uses aria-disabled to stay focusable.',
@@ -447,8 +451,8 @@ export const docsDense = {
'hover/active use backgroundImage linear-gradient overlay on base bg',
'destructive variant uses colorTokens.negative for focus outline',
'endContent wrapped in <span> w/ color:inherit, matches button text across variants',
- 'icon w/o children=icon-only: square (aspectRatio:1/1), label=aria-label, any ReactNode as icon',
- 'endContent ignored for icon-only to preserve square ratio',
+ 'isIconOnly=true: square (aspectRatio:1/1), label=aria-label, any ReactNode as icon',
+ 'endContent ignored when isIconOnly to preserve square ratio',
'prefer XDSButton over <div onClick> for a11y: keyboard nav, focus management, screen reader',
'icon-only suits toolbars, action grids, compact controls',
'onClick fires before onClickAction; preventDefault in onClick stops onClickAction',
@@ -456,7 +460,7 @@ export const docsDense = {
'disabled clears backgroundImage:none to prevent hover tint leaking through opacity',
],
propDescriptions: {
- label: 'accessible label; aria-label for icon-only buttons',
+ label: 'accessible label; visible text by default, aria-label when isIconOnly',
variant: 'visual style variant',
size: 'size variant',
type: 'HTML button type; defaults to "button"',
@@ -464,9 +468,10 @@ export const docsDense = {
value: 'HTML value for form submission',
form: 'associates button with form element by ID',
isLoading: 'shows spinner+disables interaction; announces via live region',
- icon: 'icon element; w/o children renders square icon-only button',
- children: 'w/ icon, text rendered next to icon',
- endContent: 'trailing icon/badge after label; accepts XDSIcon or XDSBadge; ignored for icon-only; color inherited',
+ icon: 'icon element rendered before label text',
+ isIconOnly: 'when true, renders square icon-only button; label becomes aria-label',
+ children: 'optional visible content; rendered instead of label when provided',
+ endContent: 'trailing icon/badge after label; ignored when isIconOnly; color inherited',
tooltip: 'tooltip on hover',
onClick: 'standard click handler; fires before onClickAction',
onClickAction: 'async click handler; shows loading while promise pending',
diff --git a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
index a2224e5668..225ed18420 100644
--- a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
+++ b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
@@ -116,7 +116,7 @@ export const docs = {
],
notes: [
'Uses `useXDSLayer` with `mode: "context"` for CSS anchor positioning',
- 'Uses `XDSButton` internally β€” chevron is passed via `endContent` and auto-hidden for icon-only buttons',
+ 'Uses `XDSButton` internally β€” chevron is passed via `endContent` and auto-hidden when `isIconOnly` is true',
'Items are tracked via the `items` prop to enable keyboard navigation',
'Light dismiss is enabled by default (clicking outside closes menu)',
],
diff --git a/packages/core/src/DropdownMenu/XDSDropdownMenu.tsx b/packages/core/src/DropdownMenu/XDSDropdownMenu.tsx
index 255d289cd4..379bee092f 100644
--- a/packages/core/src/DropdownMenu/XDSDropdownMenu.tsx
+++ b/packages/core/src/DropdownMenu/XDSDropdownMenu.tsx
@@ -243,8 +243,7 @@ function getSelectableItems(
* Props for customizing the dropdown button.
* Extends XDSButtonProps but omits onClick since it's managed internally.
*
- * When `icon` is set without `children`, renders as an icon-only button
- * (square, with `label` as aria-label). Pass `children` to get icon + visible text.
+ * Set `isIconOnly` to render as an icon-only button (square, with `label` as aria-label).
*/
export type XDSDropdownMenuButtonProps = Omit<XDSButtonProps, 'onClick'>;
@@ -287,8 +286,7 @@ export interface XDSDropdownMenuProps {
/**
* Whether to show a chevron indicator on the trigger button.
- * Automatically hidden for icon-only buttons (when `button.icon` is set
- * without `button.endContent`).
+ * Automatically hidden for icon-only buttons (when `button.isIconOnly` is true).
* @default true
*/
hasChevron?: boolean;
diff --git a/packages/core/src/TopNav/XDSTopNavItem.tsx b/packages/core/src/TopNav/XDSTopNavItem.tsx
index c3dcf930ed..c2cb4605fd 100644
--- a/packages/core/src/TopNav/XDSTopNavItem.tsx
+++ b/packages/core/src/TopNav/XDSTopNavItem.tsx
@@ -130,6 +130,7 @@ export interface XDSTopNavItemProps extends XDSBaseProps<HTMLAnchorElement> {
isDisabled?: boolean;
/**
* Optional icon to display before the label.
+ * // TODO: Add isIconOnly prop for consistency with XDSButton (#1257)
* If provided without children, item becomes icon-only.
*/
icon?: ReactNode;