What accessibility means for a web application, what PrimeFaces does for you and what remains your part.
An accessible application can be used by everyone: with a keyboard instead of a mouse, with a screen reader instead of a screen, zoomed in, or with reduced motion. PrimeFaces components bring keyboard support, WAI-ARIA roles and states and visible focus indicators out of the box. A component library can only provide the building blocks though: labels, page structure, colors and content are up to the page author. This guide covers both sides.
According to the World Health Organization, about 1.3 billion people, 1 in 6 of us, live with a significant disability. Many more are limited temporarily or by the situation: a broken arm, a screen in bright sunlight, a video in a noisy train. Designing for the four groups below improves the application for all of them.
Blindness, low vision and color blindness. People zoom the page, change colors or use a screen reader such as NVDA, JAWS, VoiceOver or TalkBack, which reads the page from its markup. The content therefore has to make sense without seeing it.
Deafness and hearing loss. Audio and video need a textual alternative: captions and transcripts. Never signal something by sound alone.
Paralysis, tremor or a missing limb. A mouse is often not an option; people use the keyboard, a switch, a head pointer or voice control. Everything has to be reachable and operable with the keyboard, and targets must not be tiny.
Learning disabilities, dyslexia, attention deficits. Clear language, a consistent layout, helpful error messages and no time pressure help here, and they are simply good design for every user.
The Web Content Accessibility Guidelines (WCAG) of the W3C are the reference, currently in version 2.2. Their criteria are grouped by four principles: content has to be perceivable, operable, understandable and robust. Each criterion has a level: A, AA or AAA. Level AA is the usual target.
Many countries made accessibility a legal requirement, and the laws refer to WCAG level AA in practice. The best known are Section 508 in the US, the Web Accessibility Directive for the public sector of the European Union, and the European Accessibility Act, which applies since June 2025 and also covers private services such as online shops and banking.
A screen reader announces what an element is and offers shortcuts to jump between headings and regions. A page built
from div elements with style classes gives it nothing to work with:
<div class="header">
<div class="header-text">Orders</div>
</div>
<div class="nav"></div>
<div class="main">
<div class="content"></div>
<div class="sidebar"></div>
</div>
<div class="footer"></div>
The same layout with semantic elements is understood without any extra attribute. Facelets pages are XHTML, so these elements can be used directly:
<header>
<h1>Orders</h1>
</header>
<nav></nav>
<main>
<article></article>
<aside></aside>
</main>
<footer></footer>
A button can be focused with Tab, triggered with Enter and Space and is
announced as a button. A div with a click handler has none of this, however much it looks like a button.
Try it with the keyboard: the first one receives the focus, the second one is skipped.
<p:commandButton value="Save" action="#{orderView.save}"/>
<!-- no focus, no keyboard, no role -->
<div class="fancy-button" onclick="save()">Save</div>
Every control needs a name that can be read out. For an input this is its label: p:outputLabel is linked
to the input with for, a click on it focuses the input, and it shows the required indicator on its own.
A button that only shows an icon has no text, it gets its name with ariaLabel. Images need an
alt text, decorative icons are hidden with aria-hidden="true".
<p:outputLabel for="email" value="Email"/>
<p:inputText id="email" value="#{orderView.email}" required="true"/>
<p:message for="email"/>
<p:commandButton icon="pi pi-trash" ariaLabel="Delete order" action="#{orderView.delete}"/>
HTML has no element for a tab view, a tree or a dialog. WAI-ARIA (Accessible Rich Internet Applications) fills this gap with attributes that
describe such widgets to a screen reader: a role says what the element is (dialog,
tablist, checkbox), states and properties describe it
(aria-checked, aria-expanded, aria-labelledby).
ARIA only describes, it does not add behavior. A checkbox built from a div needs the role, the state,
a tabindex and a key handler, and all of them have to be kept in sync by script:
<span id="remember-label">Remember Me</span>
<div class="fancy-checkbox" role="checkbox" aria-checked="false" aria-labelledby="remember-label"
tabindex="0" onclick="toggle(this)" onkeydown="toggleOnSpace(event)"></div>
The better way is to keep the native element and only replace its look. This is what p:selectBooleanCheckbox
does: the styled box sits next to a real checkbox that is hidden visually, but not from the keyboard and the screen
reader. Focus, the Space key and the checked state come from the browser.
<div class="p-selectbooleancheckbox p-chkbox p-component">
<div class="p-hidden-accessible">
<input type="checkbox" aria-labelledby="..."/>
</div>
<div class="p-chkbox-box">...</div>
</div>
dialog with aria-modal, a confirm dialog an
alertdialog, and the focus returns to where it was when the dialog closes.aria-required and
aria-invalid, so a failed validation is not only a red border.p:messages, p:message and p:growl are live
regions (aria-live): a screen reader reads the messages of an Ajax request without a page reload.aria section of the client side locale and can be translated or changed.prefers-reduced-motion animations and transitions are off,
with prefers-reduced-transparency there is no blur, and icons and focus rings stay visible in the
high contrast mode of Windows.WCAG level AA asks for a contrast ratio of at least 4.5:1 between text and its background, and 3:1 for large text, icons and the borders of controls. Check it whenever you change the primary color or a token of the theme.
About 1 in 12 men cannot tell some colors apart, most often red and green. A state must therefore not be shown by color only: add a text or an icon to an error, a status or a required field.
Two saturated colors of similar brightness next to each other seem to flicker, and the text is hard to read although the colors are clearly different.
On a dark background, highly saturated colors strain the eyes and often miss the contrast. Lighter, desaturated shades work better.
The components cannot know your content. These points are up to the page:
ariaLabel, every image an alt text.h1, headings in order without skipping a level, and the landmarks
header, nav and main.lang attribute of the page is set, so the screen reader picks the right voice.