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 :
|
highlightTarget |
‘instant’ | The allowed values include enabled or disabled :
|
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:
|
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:
|
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 .
Menu, Group and Menuitem Labeling
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. |
Landmark Region Names
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:
data-skipto
attribute- 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!