import { SkipLink } from '@uhg-abyss/web/ui/SkipLink';

Overview

SkipLink provides keyboard users a convenient way to avoid pressing tab repeated to skip through sections of a page without changing its visual presentation. It's a common technique to meet accessibility requirements for keyboard operation and usability.

From a keyboard usability and accessibility perspective, skip links are appropriate when there are seven or more tab stops repeated across multiple pages or complex components such as DataTable.

Common applications

• Skip to main content: most common use, see example below
• Start of main content / results: to return to start of page content or search results when at bottom of a page
• Skip to search results: to bypass all filters and pagination control on a search results page
• Skip to next column: for columnated content with 7 or more tab stops such as a flyout menu
• Skip to topic: to bypass left navigation or "table of content" links used for lengthy content such as terms and conditions

Note: To see the Skip Links in the following examples, press the "Rest focus" button (the topmost button in the code viewer), then press the Tab key.

Variant

Use the variant prop to change the styling. The possible options are 'default' or 'alt'.

The 'alt' variant should only be used when in a block of text and/or when using the alt color scheme to provide clear visual distinction. See the design documentation for more details.

Positioning

By default, the SkipLink is styled with:

• position: absolute
• top: 24px
• left: 24px

This positioning means:

• It appears 24px from the top-left of the nearest positioned ancestor (relative, absolute, fixed, or sticky).
• If no ancestor is positioned, it's 24px from the top-left of the page.

CSS positioning

You can adjust the positioning using the css prop to change values like position, top, left, right, or bottom. Look at the examples below to see how different positioning values affect where the skip link appears.

Ref positioning

You can use the forwarded ref to directly access the skip link's DOM element and update its styles or attributes

The example below shows the skip link's top position being adjusted based on whether the navbar is visible or hidden.

Targeting elements

Use the skipToSelector prop to control where the SkipLink will move focus when activated. This prop accepts either:

• A CSS selector string (passed directly to document.querySelector)
• A function that returns a DOM element
• A ref pointing to a DOM element

This allows you to target specific parts of your page for quick navigation, improving accessibility and usability.

Common targeting approaches: data-testid, className, ref and text content search.

Skip to main content example

The most common skip link is "Skip to main content" at the very start of a page. This allows keyboard users to save time by bypassing the numerous tab stops (links, buttons, fields, etc.) in the page header and start consuming its content.

For more information on this topic, see the Accessibility Knowledge Center's topic: Enable direct access to main content.

DataTable example

Tab into the table below to see how the SkipLink can be integrated with a data table component. The example demonstrates two skip links: one that allows users to skip directly to the table, and another that lets users skip back to the global search at the top.

SkipLink Props

Name	Type	Default	Required	Description
className	string	-	-	CSS class name to apply to each element within the component
css	Abyss.CSSProperties | Partial<Record<`abyss-${T}`, Abyss.CSSProperties>>	-	-	Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation See CSS Prop Styling for more information
data-testid	string	-	-	Suffix used to create a unique ID used for automated testing See Component Testing for more information
disableDefaultProviderProps	boolean	false	-	If set to true, the component will not use the DefaultPropsProvider values. If you aren’t using the DefaultPropsProvider, this prop can be ignored.
skipToSelector	string | (() => HTMLElement | null)	-	-	CSS selector for the element to skip to. If provided, clicking the skip link will focus and scroll to this element.
variant	"default" | "alt"	'default'	-	The visual variant of the Link

SkipLink Classes

Class Name	Description
.abyss-skip-link-root	Root skip link element

SkipLink is a solution to meet ACoE checkpoint CP 2.41 Bypass Blocks - Web and conform to WCAG Success Criterion 2.4.1: Bypass Blocks.

Component Tokens

Note: Click on the token row to copy the token to your clipboard.

Search tokens

SkipLink Tokens

Token Name	Value
skip-link.color.surface.container	#FFFFFF
skip-link.border-radius.all.link	500px
skip-link.spacing.padding.horizontal.link	24px
skip-link.spacing.padding.vertical.link	8px