• Settings
    • Locale
    • Change the locale of the datepicker, schedule and client side validation messages.

      Language
      English
      English
      English
      French
      German
      German
      German
      Italian
      Korean
      Spanish
      Catalan
      Dutch
      Portuguese
      Portuguese
      Arabic
      Arabic
      Bulgarian
      Bangla
      Bosnian
      Czech
      Greek
      Estonian
      Persian
      Finnish
      Danish
      Hindi
      Indonesian
      Icelandic
      Croatian
      Japanese
      Hungarian
      Hebrew
      Georgian
      Central Kurdish
      Khmer
      Kyrgyz
      Kazakh
      Lithuanian
      Latvian
      Malay
      Norwegian
      Polish
      Romanian
      Russian
      Slovak
      Slovenian
      Serbian
      Serbian
      Swedish
      Thai
      Turkish
      Ukrainian
      Uzbek
      Vietnamese
      Chinese
      Chinese
  • Resources
Theme
Theme
Preset primefaces.THEME
Apple Liquid Glass style: translucent overlays, menus and bars that blur the page behind them, capsule buttons.
Color scheme color-scheme
Input style p-input-filled
Density data-p-density
Direction primefaces.DIR
Colors
Primary --p-primary-base
Surface --p-surface-*
Shape and motion
Button shape --p-button-border-radius
Shadows --p-*-shadow
Animations --p-transition-duration
Ripple --p-ripple-opacity
Border radius --p-border-radius-*
Typography
Focus ring
Form field
CSS
Only the tokens that differ from the preset.

                        
                    

Accessibility

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.

Who Benefits

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.

Visual

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.

Hearing

Deafness and hearing loss. Audio and video need a textual alternative: captions and transcripts. Never signal something by sound alone.

Mobility

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.

Cognitive

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.

Standards and Laws

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.

Building Blocks

Semantic HTML

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>

Native Controls First

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.

A div

<p:commandButton value="Save" action="#{orderView.save}"/>

<!-- no focus, no keyboard, no role -->
<div class="fancy-button" onclick="save()">Save</div>

Labels and Names

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}"/>

WAI-ARIA

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>

What PrimeFaces Does for You

  • Keyboard and ARIA. Roles, states and keyboard handling are part of the components and need no configuration. A dialog for example is a dialog with aria-modal, a confirm dialog an alertdialog, and the focus returns to where it was when the dialog closes.
  • Form state. Required and invalid inputs are rendered with aria-required and aria-invalid, so a failed validation is not only a red border.
  • Announcements. 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.
  • Localized texts. Texts that only a screen reader reads, such as the close button of a dialog, come from the aria section of the client side locale and can be translated or changed.
  • User preferences. With 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.
  • Themes. Every preset has a visible focus ring, a light and a dark color scheme, and small icon controls get a hit area of at least 24px as asked by WCAG 2.2.

Colors

Contrast

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.

GOOD
5.2:1
BAD
2.5:1

Not by Color Alone

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.

Vibration

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.

VIBRATE
1.0:1

Dark Mode

On a dark background, highly saturated colors strain the eyes and often miss the contrast. Lighter, desaturated shades work better.

Indigo 600
2.8:1
Indigo 200
11.9:1

Checklist

The components cannot know your content. These points are up to the page:

  • Every input has a label, every icon button an ariaLabel, every image an alt text.
  • The page has one h1, headings in order without skipping a level, and the landmarks header, nav and main.
  • The lang attribute of the page is set, so the screen reader picks the right voice.
  • Everything works with the keyboard alone, in a sensible order, and the focus is always visible.
  • Text and controls have enough contrast, and no information is given by color alone.
  • The page still works zoomed to 200% and on a narrow screen.

Testing

  • Keyboard. Put the mouse away and use the page with Tab, Shift+Tab, the arrow keys, Enter, Space and Escape. This takes five minutes and finds most of the serious problems.
  • Screen reader. NVDA is free for Windows, VoiceOver is part of macOS and iOS, TalkBack of Android.
  • Automated checks. axe, WAVE or Lighthouse in the browser developer tools find missing labels, wrong ARIA attributes and low contrast. They only find a part of the problems, so they do not replace the two tests above.