Skip Link
Skip Link provides a finished, visible-on-focus bypass link and its matching primary-content destination. Atom owns native anchor behavior, focus transfer, scrolling, target focusability, composition, and refs; Brick owns the overlay presentation and stable customization hooks.
Built from the published package
Know when Skip Link is the right part
Use it when
Use Skip Link near the start of pages that repeat a header, navigation,
sidebar, search area, or other block before primary content. Place
SkipLink.Root before that repeated content and pair it with one matching
SkipLink.Target around the intended main region.
The application—not AppBar, Sidebar, or Brick—owns page placement. Root should be the first useful focusable control. One pair is sufficient for most pages.
Choose another path when
Do not use Skip Link for an ordinary inline destination, table of contents, pagination, route navigation, or disclosure. Do not add a duplicate pair when the page already has an equally usable bypass mechanism. Use Link for ordinary links and Visually Hidden for text that should never become visually present.
Installation and imports
Import the global Brick stylesheet once:
The complete stylesheet above is the recommended default. For a measured route-aware build, replace it with the shared foundation and this component's stylesheet:
Add the modular stylesheet for every other Brick component the route renders.
Do not combine modular styles with styles.css or tokens.css.
Import from the package root or focused subpath:
The focused subpath also exports SkipLinkRoot, SkipLinkTarget,
SkipLinkRootProps, and SkipLinkTargetProps for direct named composition.
Quick start
The defaults pair href="#main-content" with id="main-content".
Visual recipes and states
Skip Link intentionally has one visual recipe and no size, tone, shape, position, or motion props.
- Unfocused Root is fixed and translated beyond the viewport while remaining keyboard focusable.
- Focused Root appears immediately on an elevated neutral surface with accent border, readable body typography, shadow, and strong focus ring.
- Hover and active paint apply only while the link remains focused.
- Target receives Brick identity but no component layout or paint.
- Light and dark appearance scopes substitute semantic tokens.
- Forced colors use system text, surface, link, and highlight colors.
Examples
Custom destination
Native-only fragment navigation
API
Start with the public parts and root options below. Components with multiple parts separate each area into its own named subsection.
SkipLink.Root
SkipLink.Root accepts Atom's native anchor props with these focused additions
and defaults:
| Prop | Type | Default | Purpose |
|---|---|---|---|
href | `#${string}` | "#main-content" | Matching same-page destination |
focusTarget | boolean | true | Focus and scroll the existing destination |
children | ReactNode | "Skip to main content" | Localized link name |
render | Atom render adapter | — | Replace the default anchor while preserving semantics |
asChild | boolean | false | Merge into one authored semantic child |
Native anchor props, click handlers, classes, styles, data attributes, custom
slots, and an HTMLAnchorElement ref pass through.
SkipLink.Target
| Prop | Type | Default | Purpose |
|---|---|---|---|
id | string | "main-content" | Matching fragment ID |
tabIndex | number | -1 | Programmatic focus without another Tab stop |
children | ReactNode | — | Primary content |
render | Atom render adapter | — | Replace the default main |
asChild | boolean | false | Merge into one authored landmark child |
Native main props, classes, styles, data attributes, custom slots, and an
HTMLElement ref pass through.
Accessibility
- Put Root before repeated content and make it the first useful focus target.
- Write concise localized text that names the destination.
- Keep Root and Target fragment identifiers unique and matching.
- Keep the default native anchor and
mainsemantics unless the composed host supplies equivalent semantics. - Do not hide Root with
display:none,visibility:hidden, Visually Hidden, or a negativetabIndex. - Tab focuses Root; Enter activates it. Atom moves focus and scrolls to Target.
- The next Tab continues from the primary content.
- Preventing the click also prevents Atom's focus/scroll behavior.
focusTarget={false}opts into native fragment navigation only.- Brick adds no custom ARIA role or keyboard model.
Skip Link is one sufficient way to meet WCAG 2.4.1 Bypass Blocks; applications remain responsible for their complete page conformance.
Responsive behavior
The revealed link uses logical insets, a bounded viewport-relative maximum width, wrapping text, and no transition. Long localized labels remain inside narrow viewports and the position mirrors in RTL. Applications should test the real sticky header, browser chrome, safe-area policy, and supported 400% zoom layout; Brick does not guess a page-specific scroll offset for Target.
Styling and tokens
Customization
Change paint through documented variables while keeping the native focus and target contract:
Consumer classes and inline styles follow normal cascade rules. If a product requires an always-visible bypass link, use the stable Root class in that product's shell policy; Brick does not add a second behavior or public variant.
Tokens and CSS hooks
Stable classes:
.brick-skip-link.brick-skip-link__target
Both parts expose a stable data-slot: skip-link on Root and
skip-link-target on Target. An authored data-slot overrides the default.
Public Root variables:
| Variable | Purpose |
|---|---|
--brick-skip-link-background | Revealed surface |
--brick-skip-link-foreground | Link text |
--brick-skip-link-border-color | Revealed boundary |
--brick-skip-link-border-width | Boundary width |
--brick-skip-link-radius | Boundary radius |
--brick-skip-link-shadow | Elevated shadow |
--brick-skip-link-focus-ring | Focus outline |
--brick-skip-link-inset-block | Viewport block-start inset |
--brick-skip-link-inset-inline | Logical viewport inline-start inset |
--brick-skip-link-max-inline-size | Long-label width bound |
--brick-skip-link-z-index | Overlay layer |
Advanced reference
Open these details only when you need to inspect DOM ownership, native forwarding, or lower-level composition.