Utilities / Accessible Icon

Accessible Icon

Makes a decorative icon accessible by giving it a screen-reader-only label.

Announced as “Open search, button”.

razor

<button type="button">
    <NaviusAccessibleIcon Label="Open search">
        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor"
             aria-hidden="true" focusable="false">
            <circle cx="11" cy="11" r="7" />
            <line x1="21" y1="21" x2="16.65" y2="16.65" />
        </svg>
    </NaviusAccessibleIcon>
</button>

Features

Renders your icon verbatim, then appends a visually-hidden label so the graphic gains an accessible name.
Introduces no wrapper element; the icon's layout is untouched.
The hidden label stays in the accessibility tree but is removed from the visual layout (no display:none).
Label is EditorRequired, so a missing name is a build-time warning.

Installation

Reference the Navius.Primitives package for the headless primitive, or vendor its source with the CLI: navius add copies the brain files it depends on.

Terminal bash

navius add accessible-icon

Anatomy

Import the part and wrap your icon with it.

razor

@using Navius.Primitives.Components.AccessibleIcon

<NaviusAccessibleIcon Label="Notifications">
    <svg><!-- decorative icon --></svg>
</NaviusAccessibleIcon>

API Reference

Root

Renders the icon ChildContent unchanged, then a visually-hidden span carrying the accessible name. Does not render a wrapper element.

Prop	Type	Default
Label	string	- (EditorRequired)
ChildContent	RenderFragment?	-
Attributes	IDictionary<string, object>?	-

Data attributes

Data attribute	Values
[data-navius-accessible-icon]	Present on the visually-hidden label span

Unmatched attributes are forwarded to the visually-hidden label span.

Accessibility

A wordless icon (for example an inline <svg>) has no accessible name, so a screen reader announces nothing useful. This utility appends a visually-hidden <span> containing Label; the span is positioned off-screen rather than hidden with display:none, so it remains in the accessibility tree and supplies the name.

Mark the icon itself decorative with aria-hidden="true" (and focusable="false" on SVGs) so it is not announced twice. When the icon sits inside an interactive control, the hidden label becomes that control's accessible name.

This is a static utility with no interaction model of its own, so it defines no keyboard behaviour. Any keyboard handling belongs to the surrounding control (such as a <button>).