# Font Awesome 7 Accessibility Best Practices: aria-hidden and sr-only Implementation

> Learn Font Awesome 7 accessibility best practices. Implement aria-hidden and sr-only for screen reader compatibility. Ensure icons are accessible to all users.

- Repository: [Font Awesome/Font-Awesome](https://github.com/FortAwesome/Font-Awesome)
- Tags: best-practices
- Published: 2026-03-01

---

**Font Awesome 7 automatically injects `aria-hidden="true"` into icons that lack labeling attributes, while meaningful icons require explicit `aria-label`, `title`, or an adjacent `.sr-only` element to ensure full screen reader compatibility.**

Font Awesome 7 accessibility features are engineered directly into the JavaScript core to help developers build inclusive interfaces without manual ARIA management. The library intelligently distinguishes between decorative and semantic icons during the SVG transformation process, applying appropriate attributes based on the presence of labeling metadata. Understanding the internal logic in [`js/fontawesome.js`](https://github.com/FortAwesome/Font-Awesome/blob/main/js/fontawesome.js) ensures your implementations comply with WCAG standards while maintaining visual fidelity.

## How Font Awesome 7 Detects Decorative Icons

The accessibility logic resides in **[`js/fontawesome.js`](https://github.com/FortAwesome/Font-Awesome/blob/main/js/fontawesome.js)**, specifically within the SVG construction routines. When transforming an `<i>` element into an SVG, the library builds a `content` object (lines 2,521–2,562) that determines whether the icon conveys meaning.

```js
// js/fontawesome.js – lines 2,521–2,562
var content = {
  children: [],
  attributes: _objectSpread2(_objectSpread2({}, extra.attributes), {}, {
    'data-prefix': prefix,
    'data-icon': iconName,
    'class': attrClass,
    'role': extra.attributes.role || 'img',
    'viewBox': "0 0 ".concat(width, " ").concat(height)
  })
};
if (!isLabeled(extra.attributes) && !extra.attributes['aria-hidden']) {
  content.attributes['aria-hidden'] = 'true';
}

```

The **`isLabeled`** function (lines 2,423–2,429) checks for the presence of `aria-label`, `aria-labelledby`, `title`, or `role` attributes. If none exist, Font Awesome automatically sets `aria-hidden="true"`, effectively hiding purely decorative icons from assistive technologies.

## When to Use aria-hidden Versus Accessible Labels

Choosing the correct accessibility pattern depends on whether the icon conveys information or merely decorates existing content.

**Decorative icon (no semantic value)**
If the icon repeats information already present in text, Font Awesome 7 adds `aria-hidden="true"` automatically. No additional markup is required.

**Icon replacing visible text**
When an icon serves as the only content within a button or link, you must provide an accessible name using `aria-label` or `title`.

**Icon with screen-reader-only companion**
For visual indicators that require context for non-sighted users, combine `aria-hidden="true"` on the icon with a separate `.sr-only` element.

## Implementing sr-only Text with Font Awesome 7

Font Awesome 7 does not ship with a built-in **`.sr-only`** utility class. You must define this CSS yourself or import it from a framework like Bootstrap. This class visually hides content while keeping it available to screen readers.

```css
/* Custom .sr-only definition – add to your stylesheet */
.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border: 0;
}

```

Combine this with Font Awesome icons by hiding the visual element and exposing text:

```html
<i class="fa-solid fa-envelope" aria-hidden="true"></i>
<span class="sr-only">Send message</span>

```

Because the icon carries `aria-hidden="true"` (added automatically by the library), only the `.sr-only` text is announced by screen readers.

## Configuring Global Accessibility Defaults

You can customize default accessibility behavior through the **`window.FontAwesomeConfig`** object, initialized around line 1,178 in [`js/fontawesome.js`](https://github.com/FortAwesome/Font-Awesome/blob/main/js/fontawesome.js). The default configuration includes:

```js
{
  styleDefault: 'solid',
  familyDefault: 'classic',
  cssPrefix: 'fa',
  replacementClass: 'svg-inline--fa',
  autoReplaceSvg: true,
  autoAddCss: true
}

```

To override the default `role` for all icons (changing from `'img'` to `'presentation'`), set the global config before the library loads:

```js
window.FontAwesomeConfig = {
  role: 'presentation'
};

```

Alternatively, override per-icon using standard HTML attributes:

```html
<i class="fa-solid fa-user" role="img" aria-label="User profile"></i>

```

## Accessibility Metadata in Source Files

The repository maintains accessibility classifications in its metadata pipeline. Icons relevant to accessibility concerns are tagged in **[`metadata/icons.yml`](https://github.com/FortAwesome/Font-Awesome/blob/main/metadata/icons.yml)** (line 3,751) and **[`metadata/categories.yml`](https://github.com/FortAwesome/Font-Awesome/blob/main/metadata/categories.yml)** (line 27). While these tags do not affect runtime rendering, they guide documentation generation and help developers identify icons commonly used for accessibility interfaces.

## Practical Code Examples

### Automatic aria-hidden on decorative icons

```html
<!-- Font Awesome automatically adds aria-hidden="true" -->
<i class="fa-solid fa-camera"></i>

```

### Explicit labeling for standalone icons

```html
<i class="fa-solid fa-search" role="img" aria-label="Search"></i>

```

### Icon paired with screen-reader-only text

```html
<i class="fa-solid fa-home" aria-hidden="true"></i>
<span class="sr-only">Home navigation</span>

```

### Dynamic icon creation via JavaScript API

```js
// FontAwesome.icon automatically applies aria-hidden if no label provided
const icon = FontAwesome.icon({ prefix: 'fas', iconName: 'house' });
document.body.appendChild(icon.node);

```

## Summary

- **Font Awesome 7 accessibility** is handled automatically in [`js/fontawesome.js`](https://github.com/FortAwesome/Font-Awesome/blob/main/js/fontawesome.js) via the `isLabeled` function, which injects `aria-hidden="true"` when icons lack `aria-label`, `aria-labelledby`, `title`, or `role` attributes.
- **Decorative icons** require no intervention; the library hides them from screen readers by default.
- **Semantic icons** need explicit labels via `aria-label` or `title` attributes to expose accessible names.
- **`.sr-only` text** must be implemented with custom CSS, as Font Awesome does not provide this utility class.
- **Global defaults** can be modified via `window.FontAwesomeConfig` to set site-wide role preferences.

## Frequently Asked Questions

### Does Font Awesome 7 automatically add aria-hidden to all icons?

No. Font Awesome 7 checks for labeling attributes using the `isLabeled` function in [`js/fontawesome.js`](https://github.com/FortAwesome/Font-Awesome/blob/main/js/fontawesome.js). Only icons lacking `aria-label`, `aria-labelledby`, `title`, or `role` receive `aria-hidden="true"` automatically.

### How do I make a Font Awesome 7 icon accessible to screen readers?

Add either an `aria-label` attribute or a `title` element to the icon markup. Alternatively, place a visually hidden `.sr-only` element adjacent to the icon and set `aria-hidden="true"` on the icon itself to prevent redundant announcements.

### Why doesn't Font Awesome include an sr-only CSS class?

Font Awesome focuses on icon rendering rather than utility classes. The `.sr-only` pattern varies across frameworks (Bootstrap, Tailwind, etc.), so the library leaves this implementation to your specific CSS architecture or UI framework.

### Can I change the default role for all icons in Font Awesome 7?

Yes. Set `window.FontAwesomeConfig = { role: 'presentation' }` before loading the library. This overrides the default `'img'` role defined in the config object around line 1,178 of [`js/fontawesome.js`](https://github.com/FortAwesome/Font-Awesome/blob/main/js/fontawesome.js).