Scripting PDF bookmarks for accessibility

21 July 2017 | Ted Page


Bookmarks are one of the principal navigation systems available in PDFs. The following simple script can be added to a PDF bookmark to enhance the accessibility and usability of forms. When the bookmark is clicked, the cursor will be placed directly inside the relevant form field, ready to go: getField("field-name").setFocus();

Adding the script

  • Open the bookmarks panel and expand it if necessary
  • At the appropriate location in the bookmarks panel press Ctrl/Cmd + B to create an untitled bookmark
  • Rename the bookmark as appropriate
  • Right-click/Ctrl + click the bookmark and select Properties
  • Click the Actions tab

You will see something like the following:

Screenshot of the bookmark properties dialogue box
Figure 1: Go to a page in this document selected in the Actions field
  • In the Actions field of the Bookmark Properties dialogue box click Go to a page in this document to highlight it
  • Press the Delete button to clear the Actions panel
  • From the Select Action dropdown in the Bookmark Properties dialogue box select Run a JavaScript
Screenshot of the Select Action dropdown menu
Figure 2: selecting Run a JavaScript to open the script editor
  • Click the Add button
  • In the JavaScript Editor dialogue box, type or paste the following script: getField("field-name").setFocus(); where field-name is the contents of the relevant form field’s name attribute
Screenshot of the Acrobat JavaScript Editor panel
Figure 3: adding the script
  • Click OK and you’re done

The result

As with most accessibility enhancements, depending on the content and layout of a form, potentially all users will benefit from scripted bookmarks. Clicking such a bookmark will take you directly to the relevant field, ready to start typing.

Although PDF bookmarks are not particularly screen reader user friendly, if screen reader users were to click such a bookmark, they will hear the field’s tooltip (label) announced and will be prompted to start inputting data.

Perhaps more importantly, someone using a high level of magnification is likely to benefit, especially if some fields have been laid out horizontally across a page as well as vertically (such layouts are not recommended, by the way, as they not only cause problems for screen magnifier users but also for people viewing on small screens).

Scripted bookmarks may also be beneficial in the context of long questions when the relevant answer space may be located some distance from, or even on a different page to, the question, or if the reader only needs to answer some questions and not others—potentially a real asset in the case of exam papers.

Screenshot of a bookmarks panel
Figure 4: a nested list of navigable bookmark links


As can be seen, bookmark scripts are quick and easy to create, and there are many cases in which having a neat, linear list of links directly into form fields will benefit many users of your forms.