Accessibility best practices

Last updated November 18, 2012. Created by jvns on June 15, 2012.
Edited by LeeHunter, sylvain_a. Log in to edit this page.

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

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,

<?php

$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.

Example:

<?php

$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.

Example:

<?php
$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'),
);
?>

Useful links

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

Make accessible Javascript widgets

Javascript widgets are very often not accessible.

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 drupal.org.

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