Accessibility best practices

Last updated on
12 December 2017

This page gives a short list of things to be aware of when developing Drupal modules, related to Accessibility.

Use tools to evaluate your module’s pages for accessibility

Use the Web Accessibility Evaluation Tool (WAVE) toolbar or another automated tool to check any pages or blocks that your module creates for accessibility issues.

Here is a list of more accessibility validation tools. These tools will not detect all accessibility problems, but are a great start.

Use the Form API appropriately

If you use the Drupal Form API, it will do a lot of work towards making your forms accessible. Make sure when using hook_form_alter and other techniques to modify forms that you are not reducing the accessibility of forms.

Use #title and #description

Every FAPI element should have the #title property set. This makes a label for the input field so that screenreader users know what the input field is for. The #title property should indicate the label associated to the form element. It should not be used for formatting other text (to create a heading, for example).

If the form element needs additional description beyond the title, set the #description property as well.

For example,

$form['pass'] = array(
  '#type' => 'password', 
  '#description' => t('Passwords must be at least 8 characters and contain a number'), 
  '#title' => t('Password'), 
  '#maxlength' => 64, 
  '#size' => 15,

Use fieldsets to group elements which belong together logically

If you are making a date or phone number field, it is best to only use one input field instead of several. However, if you need to use several input boxes (for example for the month, day, and year), then these should be grouped in a fieldset so that it is clear to screenreader users that they are all part of the same logical input field.


$form['start_date'] = array(
  '#type' => 'fieldset',
  '#title' => t('Date'),
$form['start_date']['month'] = array(
  '#type' => 'textfield',
  '#title' => t('Month'),
  '#size' => 2,
  '#maxlength' => 2,
$form['start_date']['day'] = array(
  '#type' => 'textfield',
  '#title' => t('Day'),
  '#size' => 2,
  '#maxlength' => 2,
$form['start_date']['year'] = array(
  '#type' => 'textfield',
  '#title' => t('Year'),
  '#size' => 4,
  '#maxlength' => 4,

Radio buttons and checkboxes also need to be grouped together inside a fieldset, for the same reason.


$form['dinner_pref'] = array(
  '#type' => 'fieldset',
  '#title' => t('Dinner Preference'),
$form['dinner_pref']['month'] = array(
  '#type' => 'radio',
  '#title' => t('Chinese'),
$form['dinner_pref']['day'] = array(
  '#type' => 'radio',
  '#title' => t('Indian'),
$form['dinner_pref']['year'] = array(
  '#type' => 'radio',
  '#title' => t('Burgers'),

Form field focus

While it can seem convenient to give a form field the initial focus on a page, this should only be done if that form field is or enables the primary purpose of the page. For example, on a Search This Site page, giving focus to a Search Keywords field would probably be appropriate, because searching is the primary purpose of the page. But on a Modules List page, giving focus to a Filter Keywords field would be inappropriate, because filtering the module list is far from being the page's primary purpose.

The main reason for this guideline is that a side effect of giving the focus to a form field is that screen readers will start reading the page at that field, skipping the top of the page. Users of screen readers will therefore miss out on the context provided by starting at the top, and have difficulty understanding what the page is about, since (unlike users without vision difficulties) they cannot see the entire page at a glance to understand it.

Useful links

Here are a few links discussing accessibility considerations with the Form API:

Make accessible Javascript widgets

Javascript widgets are very often not fully accessibility. Best practices recommend ensuring the basic functionality of your site then enhance this functionality with javascript and other widgets (not replace or mask basic functions).

Autocomplete widgets

You can create autocomplete widgets in Drupal 7 by setting the '#autocomplete_path' property on a form element. These widgets are accessible. If you want to use jQuery UI Autocomplete instead of Drupal's built-in version, it is accessible in version 1.9 but not in version 1.8.

Date/Calendar popup widgets

TODO: Are there any good date/calendar popup widgets?

Other custom Javascript widgets

For information on creating JavaScript widgets, see these WebAIM articles on Javascript and AJAX accessibility.

For general information see the accessibility handbook on

For information on creating accessible themes, see the accessibility section in the theming guide.