Configuration Options

All settings have a default value, a data-skipto attribute on the script element or a global configuration object (e.g. SkipToConfig) can be used to change the default values and to localize the menu text to a specific language.

Options for adding the button element

The following options are useful for identify where the menu will be in the DOM structure of the page and which elements will be used as the container for the menu button. The options are of type string.

Property default Description
containerElement ‘nav’ Container element tag name for the SkipTo.js button and menu. The default value is nav and the only other allowed value is div. Use the div value if you do not want a navigation landmark created by SkipTo.js.
displayOption ‘fixed’ The allowed values include fixed, popup, popup-border or static:
  • fixed: The button is always visible at the top of the page even when the page scrolls, making the SkipTo.js features available to all users to benefit from.
  • popup: The button is initially not visible, but becomes visible when it receives focus.
  • popup-border: Is similar to the "popup" option except the bottom border of button is always visible. The entire button becomes visible when it receives focus (e.g same a "popup" option) and when the pointer is moved over the exposed border.
    NOTE: This option makes the button and menu discoverable by pointer users, making the SkipTo.js features available to all users to benefit from.
  • static: The button is always visible at the top of the page.
highlightTarget ‘instant’ The allowed values include enabled or disabled:
  • disabled: Scrolling target into view is disabled.
  • instant: The target of the menu item is scrolled into view immediately when the item receives focus.
  • smooth: The target of the menu item is scrolled into view slowly when the item receives focus.
  • enabled (deprecated): Same as instant.
customClass none CSS class added to the container element (e.g. nav or div). Can be used for customize styling of the button and menu with author supplied stylesheet.

NOTE: The attachElement property is no longer supported due to scroll to content feature and the menu being in a fixed position at the top of the page.

Button Positioning

Property Type Default Description
positionLeft length 46% The position of the “Skip To Content” button from left margin.

Button Font Family and Font Size

Property Type Default Description
fontSize CSS font size inherit Set the CSS font-size using the configuration object. The default is inheriting the font size from the page.
fontFamily CSS font string inherit Set the CSS font-family using the configuration object. The default is inheriting the font family from the page.

Identifying Landmarks and Headings for the menu

The landmarks and ‘headings’ options are a space separated list of tag and landmark region names to identify the important landmark regions and headings on the page for the purpose of keyboard navigation. The list of landmarks and headings should be relatively short, the more items the menu contains the more time the user will need to scan and navigate to the section they want to “skip to”. The values are considered tokens to maximize compatibility with version 4 CSS selectors for these properties.

The options are of type string.

Property Default Description
landmarks ‘main search navigation complementary’ A space separated list of landmark names.
Allowed values include:
  • banner
  • complementary
  • contentinfo
  • main
  • navigation
  • region
  • search
headings ‘main-only h1 h2’ A space separated list of heading tags, when the “main-only” value is included only headings contained in the main landmark region will be included.
Allowed values include:
  • h1
  • h2
  • h3
  • h4
  • h5
  • h6
  • main-only
  • main (deprecated)

Color Theme Options

A color theme sets all the color options defined by the theme.

Property Type Default Description
colorTheme string default A predefined color scheme for skipTo

Current Color Theme Values:

  • ‘aria’ : Used in ARIA Authoring practices
  • ‘illinois’: Used by the University of Illinois at Champaign/Urbana
  • ‘uic’ : Used by the University of Illinois at Chicago
  • ‘uillinois’ : Used by the University of Illinois Administration
  • ‘uis’ : Used by the University of Illinois at Springfield
  • ‘openweba11y’ : Used by Open Web Accessibility Services

  • If you would like a theme added for your organization, please file an issue with the desired colors

Colors used for Button and Menu styling

Color values must use CSS color values, for example #8AF, rgb(40, 50, 90), #a0bf32, blue.

Property Type Default Description
buttonTextColor Color #1a1a1a Color of text for “Skip To Content” button.
buttonBackgroundColor Color #eeeeee Background color of text for “Skip To Content” button.
focusBorderColor Color #1a1a1a Border color for items with keyboard focus.
menuTextColor Color #1a1a1a Menu text color
menuBackgroundColor Color #dcdcdc Menu background color.
menuitemFocusTextColor Color #eeeeee Menuitem text color when a menuitem has focus.
menuitemFocusBackgroundColor Color #1a1a1a Menuitem text background when a menuitem has focus.

NOTE: Make sure colors meet the color contrast requirements of WCAG 2.1 for text

Internationalization (I18N)

The text labels and messages can be updated through configuration to local language requirements.

Button Labeling

The labels and messages can be localized for specific languages or reflect user preferences.

Property Default Description
buttonLabel ‘Skip to Content’ Change the text label of the menu button.
smallButtonLabel ‘SkipTo’ Change the text label of the menu button in small screen sizes.
altLabel ‘Alt’ Label for modifier key for Windows and Unix/Linux operating systems
optionLabel ‘Option’ Label for modifier key for macOS operating systems
shortcutLabel ‘shortcut’ Label for shortcut label used in defining aria-label for button.

NOTE: altButtonLabel and optionButtonLabel are deprecated as configuration options. The values are computed from buttonLabel, altLabel, optionLabel and shortcutLabel and .

The labels and messages can be localized for specific languages or reflect user preferences.

Property Default Description
menuLabel ‘Landmarks and Headings’ Change the label for the menu.
landmarkGroupLabel ‘Landmark Regions’ Menu group label for landmarks .
headingGroupLabel ‘Headings’ Menu group label for headings.
headingLevelLabel ‘Heading level’ Used for aria-label to improve labeling of heading menu items for screen reader users.

The names of landmark region names can be localized for specific languages or reflect user preferences.

Property Default Description
mainLabel ‘main’ The label in the menu for main landmarks
searchLabel ‘search’ The label in the menu for search landmarks
navLabel ‘navigation’ The label in the menu for navigation landmarks
asideLabel ‘aside’ The label in the menu for complementary landmarks
footerLabel ‘footer’ The label in the menu for contentinfo landmarks
headerLabel ‘header’ The label in the menu for banner landmarks
formLabel ‘form’ The label in the menu for form landmarks
msgNoLandmarksFound ‘No landmarks to skip to’ Message for when no landmarks are found.
msgNoHeadingsFound ‘No main headings to skip to’ Message for when no headings are found.

About Dialog

The names of landmark region names can be localized for specific languages or reflect user preferences.

Property Default Description
aboutInfoLabel ‘About SkipTo.js’ Title of the About dialog box.
aboutDesc ‘SkipTo.js is a free and open source utility to support authors in implementing the WCAG 4.2.1 Bypass Block requirement on their websites.’ A description of SkipTo.js, emphasizing it is free to use and open source.
aboutVersion ‘Version ${this.version}’ Version number.
aboutCopyright ‘BSD License, Copyright 2021-2025’ Copyright and license information.
aboutHappy ‘Happy Skipping!’ Happy message to encourage people to use SkipTo.js.

Example Settings

There are two ways for an author to configure SkipTo.js:

  1. data-skipto attribute
  2. Global variable

Settings Using Data Attribute

You can customize SkipTo.js to the features of your website by using a data-skipto attribute on the script element. Each property/value setting is separated by a semi-colon (;), and each property name and value is separated by a colon (:).

The following is a sample configuration:

<script
  data-skipto="landmarks: main search navigation; headings: main-only h1 h2 h3; colorTheme: illinois"
  src="https://skipto-landmarks-headings.github.io/page-script-5/dist/skipto.min.js">
</script>

Settings Using Global Object

You can customize SkipTo.js to the features of your website by using a global object variable.

The following is a sample configuration:

<script>
  var SkipToConfig =  {
    landmarks: 'main search navigation',
    headings: 'main-only h1 h2 h3',
    colorTheme: 'illinois'
  };
</script>

or

<script>
  window.SkipToConfig =  {};
  window.SkipToConfig.landmarks  = 'main search navigation';
  window.SkipToConfig.headings   = 'main-only h1 h2 h3';
  window.SkipToConfig.colorTheme = 'illinois';
</script>

NOTE: Configuration objects in version 4.x are still supported for compatibility with existing installations. Version 5.x is providing a less complex object for customizing SkipTo.js.

Warning Messages

The following warning messages may be rendered to the console:

Message Action
Skipto is already loaded Additional SkipTo’s are ignored
No headings found in main Searches for headings anywhere on the page
No headings found on page SkipTo menu reports no headings on the page
No landmarks found on page SkipTo menu reports no landmarks on the page
Error in heading configuration Sets configuration to look for any h1 of h2 headings
Error in landmark configuration Sets configuration to look for main search and navigation landmarks
Unsuported or deprecated configuration option “abc” “abc” option is ignored and/or default setting is used

Feedback and Reporting Issues

We welcome your feedback! Please do not hesitate to raise issues and comment on Github if something doesn’t work or you have ideas on how to improve SkipTo.js.

Happy skipping!