Skip to content

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

TypeScript

feat(TopNav): add isIconOnly prop to XDSTopNavItem (#1309)

Cindy Zhangd9b7242aff9d
diff --git a/packages/core/src/TopNav/TopNav.doc.mjs b/packages/core/src/TopNav/TopNav.doc.mjs
index f69920ef70..23ddfd15c9 100644
--- a/packages/core/src/TopNav/TopNav.doc.mjs
+++ b/packages/core/src/TopNav/TopNav.doc.mjs
@@ -132,7 +132,7 @@ export const docs = {
accessibility: [
'XDSTopNav renders a <nav> element with role="navigation" and aria-label set from the label prop',
'XDSTopNavItem sets aria-current="page" when isSelected is true',
- 'XDSTopNavItem sets aria-label for icon-only items (when icon is provided and no children or label text is visible)',
+ 'XDSTopNavItem sets aria-label when isIconOnly is true, keeping the item accessible.',
'XDSTopNavItem sets aria-disabled and tabIndex=-1 when isDisabled is true',
'XDSTopNavMenu sets aria-haspopup="true" on the trigger button',
'XDSTopNavMegaMenu sets aria-haspopup="true" and aria-expanded on the trigger button',
@@ -267,7 +267,7 @@ export const docs = {
name: 'label',
type: 'string',
description:
- 'Accessible label for the nav item. Used as visible text, or as aria-label for icon-only items.',
+ 'Accessible label for the nav item. Rendered as visible text by default. When isIconOnly is true, used as aria-label instead.',
required: true,
},
{
@@ -289,17 +289,24 @@ export const docs = {
'Whether the nav item is disabled. Sets aria-disabled and prevents interaction.',
default: 'false',
},
+ {
+ name: 'isIconOnly',
+ type: 'boolean',
+ description:
+ 'Renders the item as a square icon-only element. When true, label becomes the aria-label and visible text is hidden. Requires icon to be set.',
+ default: 'false',
+ },
{
name: 'icon',
type: 'ReactNode',
description:
- 'Optional icon to display before the label. If provided without children, the item becomes icon-only.',
+ 'Optional icon to display before the label.',
},
{
name: 'children',
type: 'ReactNode',
description:
- 'Custom content to render instead of the label text. When omitted and an icon is provided, the item becomes icon-only.',
+ 'Custom content to render instead of the label text.',
},
{
name: 'as',
@@ -1205,7 +1212,7 @@ export const docsDense = {
accessibility: [
'XDSTopNav renders <nav> w/ role="navigation"+aria-label from label prop.',
'XDSTopNavItem sets aria-current="page" when isSelected.',
- 'XDSTopNavItem sets aria-label for icon-only items (icon provided w/o children or visible label).',
+ 'XDSTopNavItem sets aria-label when isIconOnly is true.',
'XDSTopNavItem sets aria-disabled+tabIndex=-1 when isDisabled.',
'XDSTopNavMenu sets aria-haspopup="true" on trigger button.',
'XDSTopNavMegaMenu sets aria-haspopup="true"+aria-expanded on trigger button.',
@@ -1239,11 +1246,11 @@ export const docsDense = {
name: 'XDSTopNavItem',
description: 'Nav link for XDSTopNav startContent; renders as anchor w/ hover+selected states.',
propDescriptions: {
- label: 'Visible text or aria-label for icon-only items.',
+ label: 'Visible text or aria-label when isIconOnly is true.',
href: 'Navigation URL.',
isSelected: 'Sets aria-current="page"+highlighted styles.',
isDisabled: 'Sets aria-disabled, prevents interaction.',
- icon: 'Icon before label. W/o children becomes icon-only.',
+ icon: 'Icon before label.',
children: 'Custom content instead of label text.',
as: 'Custom link component. Overrides XDSLinkProvider default. Must accept href, className, style, children.',
},
diff --git a/packages/core/src/TopNav/XDSTopNav.test.tsx b/packages/core/src/TopNav/XDSTopNav.test.tsx
index f9914b3e9a..fb03592974 100644
--- a/packages/core/src/TopNav/XDSTopNav.test.tsx
+++ b/packages/core/src/TopNav/XDSTopNav.test.tsx
@@ -254,6 +254,20 @@ describe('XDSTopNavItem', () => {
expect(screen.getByText('Settings')).toBeInTheDocument();
});
+ it('hides label and sets aria-label when isIconOnly', () => {
+ render(
+ <XDSTopNavItem
+ label="Settings"
+ href="#"
+ icon={<span data-testid="icon">⚙️</span>}
+ isIconOnly
+ />,
+ );
+ expect(screen.getByTestId('icon')).toBeInTheDocument();
+ expect(screen.queryByText('Settings')).not.toBeInTheDocument();
+ expect(screen.getByRole('link')).toHaveAttribute('aria-label', 'Settings');
+ });
+
it('handles click events', async () => {
const user = userEvent.setup();
const handleClick = vi.fn();
diff --git a/packages/core/src/TopNav/XDSTopNavItem.tsx b/packages/core/src/TopNav/XDSTopNavItem.tsx
index c2cb4605fd..930bb25e10 100644
--- a/packages/core/src/TopNav/XDSTopNavItem.tsx
+++ b/packages/core/src/TopNav/XDSTopNavItem.tsx
@@ -2,7 +2,7 @@
/**
* @file XDSTopNavItem.tsx
- * @input Uses React, AnchorHTMLAttributes, ReactNode
+ * @input Uses React, ReactNode, XDSBaseProps, XDSLinkComponentType
* @output Exports XDSTopNavItem component and XDSTopNavItemProps
* @position Navigation item component for XDSTopNav startContent
*
@@ -115,7 +115,8 @@ export interface XDSTopNavItemProps extends XDSBaseProps<HTMLAnchorElement> {
as?: XDSLinkComponentType;
/**
* The accessible label for the nav item.
- * Used as visible text, or as aria-label for icon-only items.
+ * Rendered as visible text by default. When `isIconOnly` is true,
+ * used as aria-label instead.
*/
label: string;
/**
@@ -128,15 +129,19 @@ export interface XDSTopNavItemProps extends XDSBaseProps<HTMLAnchorElement> {
* @default false
*/
isDisabled?: boolean;
+ /**
+ * Renders the item as a square icon-only element.
+ * When true, `label` becomes the aria-label and visible text is hidden.
+ * Requires `icon` to be set.
+ * @default false
+ */
+ isIconOnly?: 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;
/**
* Optional content to render instead of the label.
- * If omitted and icon is provided, item becomes icon-only.
*/
children?: ReactNode;
/**
@@ -160,7 +165,7 @@ export interface XDSTopNavItemProps extends XDSBaseProps<HTMLAnchorElement> {
* <>
* <XDSTopNavItem label="Home" href="/" isSelected />
* <XDSTopNavItem label="Products" href="/products" />
- * <XDSTopNavItem label="Settings" href="/settings" icon={<GearIcon />} />
+ * <XDSTopNavItem label="Settings" href="/settings" icon={<GearIcon />} isIconOnly />
* </>
* }
* />
@@ -171,6 +176,7 @@ export function XDSTopNavItem({
label,
isSelected = false,
isDisabled = false,
+ isIconOnly = false,
icon,
children,
size = 'md',
@@ -182,8 +188,6 @@ export function XDSTopNavItem({
}: XDSTopNavItemProps) {
const LinkComponent = useXDSLinkComponent(as);
const renderMode = useXDSTopNavRenderMode();
- const isIconOnly = icon != null && children == null && !label;
- const showLabel = !isIconOnly;
// =========================================================================
// Drawer mode — render as a SideNavItem-style vertical list element
@@ -192,6 +196,7 @@ export function XDSTopNavItem({
return (
<LinkComponent
ref={ref}
+ aria-label={isIconOnly ? label : undefined}
aria-current={isSelected ? 'page' : undefined}
aria-disabled={isDisabled || undefined}
tabIndex={isDisabled ? -1 : undefined}
@@ -210,7 +215,7 @@ export function XDSTopNavItem({
)}
{...props}>
{icon}
- {children ?? label}
+ {!isIconOnly && (children ?? label)}
</LinkComponent>
);
}
@@ -240,7 +245,7 @@ export function XDSTopNavItem({
)}
{...props}>
{icon}
- {showLabel && (children ?? label)}
+ {!isIconOnly && (children ?? label)}
</LinkComponent>
);
}