Part of a Whole

My name is Nicolas Steenhout.
I speak, train, and consult about inclusion, accessibility and disability.

Listen to the A11y Rules Podcast. And become a patron on Patreon.
Become a Patron!

Show/Hide password accessibility and password hints tutorial

“Show password” and “password hints” are vital aspects of usable password form fields. We encounter them often. They often are not accessible. Here are a few suggestions to improve “show/hide password accessibility” as well as “password hint accessibility”.


Overview: This post in a tiny nutshell

Accessibility is important for many groups of users with or without disabilities. We must ensure that both “password hints” and “show password” functionality are accessible. To do this, we programmatically associate password hints with the input. There are several things to do to show passwords. Some of these include using a <button> to trigger the action, using a role of switch, and using the aria-pressed attribute.

Video version

A transcript for this video is available.

The trigger: What made me write this post

When you have an essential tremor, which makes it hard to type, especially on a phone screen, it’s frustrating when you can’t make visible the password you’re typing, so you don’t know if it’s failing because you mistyped it or because they are expecting a different password.

I read the previous comment by Dr. Ellen Spertus on a disability and tech related Slack. I’d been thinking a while about writing this post, but her expression of frustration was my trigger for finally doing it. Thank you Ellen!

You can also listen to Ellen talk about this in an A11y Rules Soundbite episode about essential tremors and password fields.

Background: Who am I to write about show/hide password accessibility?

I’ve been working in web accessibility for over 25 years. I train people about web accessibility and disability inclusion. I conduct web accessibility audits. And I help organizations develop a culture of accessibility and inclusion. As I said, I’d been thinking about writing a tutorial about show/hide password accessibility for many months. It’s an issue I have encountered in the last handful of audits I conducted. I hope this short accessibility lesson helps!

The code: How to actually do this

Before I explain what’s going on, here’s a live example using CodePen

See the Pen
Show password and password hints
by Nicolas Steenhout (@vavroom)
on CodePen.

Password hints: Help users know what patterns are acceptable

Password hints are important to help users know what pattern is acceptable when they create a password. It’s critical to inform users ahead of time. Entering a password and getting a validation message that the password isn’t meeting requirements is quite frustrating.

It is a problem that “password hints” are typically located after the text input where users enter a password. They are also rarely programmatically associated with the input. This means that screen reader users are likely to miss the information. This would happen whether they are using “forms mode” or “browse mode” in the assistive technology.

What needs to happen

  1. Locate the password hints within the form, before the password input. This will allow screen reader users in browse mode to discover the hint before they have to enter a password.
  2. Programmatically associate the password hint with the input using the aria-describedby attribute. This will allow screen reader users in forms mode to get the information when they reach the input.
  3. Hide the bullet list from screen readers using aria-hidden="true". The bullet list is useful for sighted users. If the actual list were included in the password hint spoken by the screen reader, it would be annoying and cumbersome.
  4. Include the list in paragraph form. Make this available only for screen reader users. Including the list that way may make it more difficult for some screen reader users if their speech rate is set to a rapid pace, but it won’t have as much of an impact as a bullet list would have.

Points 3 and 4 are arguable. This is very much a case of “it depends”. There are pros and cons on doing it both ways. Seeking feedback from screen reader users indicate that the proposed method is the best approach.

Show password: Be kind to your users

Being able to see the password is essential for many groups of people.

  • Some folks have memory issues and need to be able to see what they typed.
  • Other folks have essential tremors. They are likely to make mistakes. Not seeing what was typed makes it impossible to verify and fix.
  • Just about anyone who likes to double check what they typed in.

What needs to happen

There are several things to consider.

  1. Use a button to display or hide the password. Buttons do something (links go somewhere). Don’t use a semantically meaningless element like a <div>.
  2. Use a role of “switch” on the button. This will provide information about what the button is doing.
  3. Use an aria-pressed attribute on the button. This will inform screen reader as to the state of the input.
  4. When the button is activated:
    1. Change the value of the aria-pressed attribute.
    2. Change the input type from password to text.
    3. Change the button’s image.
  5. Provide additional information about the state change (optional).

aria-pressed attribute and aria-live

The aria-pressed attribute serves to indicate the state of the input. If it’s set to “true”, screen reader users will know that the password is displayed. If it’s set to false, they’ll know the password is hidden. This may be sufficient information for many users. But not all users.

Sighted users do not have access to ARIA values. So we change the button’s image on the fly. The image’s alt text remains “Show password” to reduce the risks of confusion since we are informing screen reader users of the change through the toggle’s pressed state.

To help further, I provide a message that the password is hidden, or shown. This is set in an ARIA live region so when the state changes, the text changes and users are notified. I use the “polite” value of the aria-live attribute as it creates a better screen reader user experience. This step is optional. Some would say that using aria-pressed is sufficient, but as a blind screen reader user says: I find that too many things don’t do what they ought to on the interwebs. Clear, consistent, and concise notification is good.

Different approaches: Other ways to accomplish a similar thing

The show/hide password method I am showing in this tutorial is one way to accomplish this task in an accessible way. There are other approaches that work. Don’t feel restrained by my suggestion. Do keep in mind what needs to happen:

  • The state of the password input field should be easily determined.
  • The function should be accessible for keyboard users, sighted or not.
  • Use semantically meaningful HTML rather than relying on ARIA.

Some sites use a checkbox. This is typically placed after the input field. I identify two issues with this. First, it may be difficult for some users to tell the checkbox is there until they navigate to it. It defeats the purpose of making the interaction easier if you don’t present the option upfront. Second, checkboxes can have 3 states (Chris Coyer spoke about this years ago!. This could cause some confusion and lead to errors. Additionally, some designers may oppose this approach as it requires more “visual pollution”, that is, more space used, and a visible label.

Other things in that code snippet

The code snippet includes a couple other things that aren’t necessary for this demonstration, but are best practices.

Required field

Typically, password fields are required. I use the aria-required attribute to programmatically inform users that the field is required. This is somewhat contrary to my general advice: “Use native HTML if it’s available rather than relying on ARIA”. But there are some accessibility issues with the required HTML5 attribute. The native HTML5 required attribute automatically announces a field as “invalid” the 1st time focus is set to it (while still empty). The aria-required attribute doesn’t & is a better choice IMHO. The required attribute also triggers a client-side validation that fails WCAG, explains Denis Boudreau on Twitter, something he noticed via user testing.

As a result, I’m using aria-required="true".


Being able to rely on autocomplete is crucial for several groups of people, including folks with cognitive impairments and folks with memory issues. As such, I’ve included the autocomplete attribute. The context of this demonstration is for a new password (hence the password hints) so I’m using a value of “new-password”. If this was a field for login in rather than signing up, I would use the value “current-password”.


Some people may not realize that there are security risks to showing your password. This is particularly true for folks using the site in public. It may also be an issue for folks with low or no vision who may not be aware of people behind them. It is often considered good practice to warn users about the security risk in showing the password. I want to keep the tutorial simple, so I am not talking about it here. But if you implement such a feature, make sure it is accessible!


This post should have given you a few ideas on how to implement a more accessible way of providing password hints and revealing passwords. With a little planning you can make the web a bit more accessible. Pass it on!

Thank you

Thanks to the blind screen reader users who helped for some logic checks on screen reader user workflows and to Nick Lee for a hand with some JavaScript for the demo.

Video transcript

Nic Steenhout

Bonjour , let’s talk about show hide password functionality and also about password hints. W e encounter these features more and more often. And that’s great. They make using the web a lot easier for a lot of people, including disabled folks. These features are particularly important for folks with memory issues, people with cognitive impairments and maybe folks who have tremors. Problem is they’re rarely built with accessibility in mind. In fact, I encountered similar features in most of the accessibility audits I conducted in the last year, and none were built accessibly. I’d been wanting to talk about show hide passwords and accessibility for a while. A message from Dr. Ellen Spertus finally prompted me to do it. Ellen said:

Nic Steenhout

When you have an essential tremor, which makes it hard to type, especially on a phone screen, it’s frustrating when you can’t make visible the password you’re typing. So you don’t know if it’s failing because you mistyped it, or because they are expecting a different password.

Nic Steenhout

First, let’s look at three sites that offer show hide password features that are not accessible: Target, Madewell, and The target website is interesting, because as some of you know, Target was sued several years ago for accessibility, they actually settled a fairly expensive lawsuit, and part of the agreement was that they would work towards improving accessibility. And they’re pretty good. But there’s something here that is a bit of a problem. So if you can’t see the screen, there is a login form. And in the Create password, there is the word show. So let’s navigate to that and see what happens.


First Name, Last Name, mobile phone number optional, create password, secure an edit text file menu, to open the autofill menu…

Nic Steenhout

So we’re on the password field. In theory, the next step stop should be the show button.


show show button. You are currently on a button inside of web content. to click this button, press Control option space.

Nic Steenhout

So I’m going to press Control option space and see what happens.


Press show button.

Nic Steenhout

So I pressed it visually, the button content has changed to hide. But I don’t get a lot of information about this.


press hide button.

Nic Steenhout

So I’ve pressed the button again. But I did not get very much information. So this experience is not really great for screen reader users using voiceover. Obviously, the experience may be somewhat different in NVDA, or jaws. I’m not going to test it here for the purpose, but I wanted to show some of the problems where you press a button, and nothing really happens.

Nic Steenhout

Here we are on the website, the registration page, there’s a form typical stuff. first name, last name, email password. In the password field, there is similar approach to what I’ve done. There’s a eye icon that should in theory, reveal the password. So let’s quickly tap to that field and see what happens.


Last name, email with a password password required secure with autofill menu password you are currently on.

Nic Steenhout

So we’re on the password field. In theory, the next step stop is going to be the eye to show or hide the password.


United States United States

Nic Steenhout

However, I skip straight to the country. So I’m going to tab backwards and see if I can get to it.


password password required invalid data secure edit text with autofill menu.

Nic Steenhout

And I can’t. They have coded this in a way that makes the eye icon not keyboard accessible. Now, as a sighted user, I can know it’s there. So I could, I guess explore ways to actually reach it. But if I was a non sighted screen reader user, I wouldn’t even know it’s there to try and find it. So this is a problem.

Nic Steenhout

Here we are on a Australian real estate website called This is a Create Account page. And as usual, there’s a Create Account form with a email address and a password. In the password input fields. There is the word show which is under linked. There’s also options for continuing with Google, Facebook or Apple. But let’s look at how the real estate site handles this. So I’m currently focused on the email address I’m going to tab to the password field and see what happens


leaving toolbar, entering real estate calm got a you create account web content, password password secure edit text with autofill menu.

Nic Steenhout

So we have the password field. The next steps up should be the show, link or button.


Create Account button.

Nic Steenhout

So again, just like the, we went straight from the password input field to the next field. And we skipped the functionality of showing the password. So let’s try and go backwards and see what happens.


Password password secure edit text, email address, edit text blank, password, password, secure edit text, Create Account button, you work.

Nic Steenhout

And the show password functionality is completely unavailable to keyboard only users sighted or not. Yet, if I go and click it with the mouse, I have the word changes from show to hide. Similar to the target experience, except that we can’t actually trigger this with the keyboard.

Nic Steenhout

You can well imagine how these experiences could be frustrating. As a developer, it’s in your power to build it so it’s accessible. Let’s look at my solution. Here’s a short demonstration of my markup in action using NVDA. I did slow down the speech write down for clarity because not everyone is used to fast speaking screen readers.


edit protected required password show password graphic clickable toggle button not pressed. Edit protected required password must be at least eight characters must have at least one number must have at least one uppercase letter must have at least one special character blank. Star Show password graphic clickable toggle button not pressed password shown pressed.

Nic Steenhout

Let’s look at my code pen, I’ll walk you through and explain what I’ve done. First, we’re looking at the password hints.

Nic Steenhout

I’ve added the hints as an unordered list for sighted users. But I’m hiding that from screen reader users. Wel’l be providing the list for screen reader users differently. We need to provide a unique ID to the container that will have the password hint for screen reader users. This is needed to programmatically associate the hints and the input. Then we provide the hints in a visually hidden span, text for screen readers only. I do this because in testing with screenreader users when I associated the unordered list itself, the experience became very verbose screen readers would announce the bullet to each time. We add the input and use aria-describedby to associate the input and the password hint. So now we have the password hints available for both sighted users and screen reader users.

Nic Steenhout

Let’s look at the show hide password function now. We need a button to trigger that. We could use a checkbox but I think a button is more accessible for a few reasons. Anyway, we add a role of switch to the button so screenreader users know it controls the state of an element. In this case the input. We use the aria-pressed attribute with the default value of false to indicate the actual state of the element. This will be changed by JavaScript when the button is activated. We add a type of button just to make sure that there’s no confusion as to the button’s purpose as opposed to a submit or reset button. So we need content for the button. We could use text and change that text based on the input state but I prefer to use an image for sighted users, the default image is going to be an eye. But an image without alt text is not very useful for screen reader users. So we add alt text. The value here is “show password.” We keep the same alt text value regardless of the button state this is to limit confusion. We are already indicated the state with aria-pressed.

Nic Steenhout

Finally, I add a visually hidden paragraph with a clear and concise message password hidden or password shown. This isn’t critical. Many would say that using aria-pressed and role switch is sufficient but not everyone is comfortable with that information only. So I assigned this a live region. So when the text changes, in this case, the image is spoken by screen readers. I use a value of polite because Who wants to be interrupted unless the sky is falling down right?

Nic Steenhout

Anyway, have a play with the code then check it out. I should point out that there are many ways to accomplish this, you can use a checkbox or you can use text instead of an image. As usual, there are pros and cons to every approach, and you’ll have to decide what works best for you. However, do make sure to remember that it needs to work well for keyboard only users sighted or not. Also, keep in mind that the interaction needs to be making sense for screen reader users.

Nic Steenhout

Thank you for listening