sp-top-nav

Overview API Changelog

Overview

<sp-top-nav> delivers site navigation, particularly for when that navigation will change the majority of the page's content and/or the page's URL when selected. All primary elements of an <sp-top-nav> should be directly accessible in the tab order, typically as <sp-top-nav-item> elements. There should only ever be one <sp-top-nav> on a page.

Refer to the Spectrum Design System documentation for visual design guidelines and the application frame patterns for usage in application contexts.

Usage

See it on NPM! How big is this package in your project? Try it on Stackblitz

yarn add @spectrum-web-components/top-nav

Import the side effectful registration of <sp-top-nav> and <sp-top-nav-item> as follows:

import '@spectrum-web-components/top-nav/sp-top-nav.js';
import '@spectrum-web-components/top-nav/sp-top-nav-item.js';

When looking to leverage the TopNav or TopNavItem base classes as a type and/or for extension purposes, do so via:

import { TopNav, TopNavItem } from '@spectrum-web-components/top-nav';

Anatomy

The <sp-top-nav> component consists of the following parts:

  • Container (<sp-top-nav>): The main navigation container component with role="navigation" that manages nav items and selection states
  • Navigation items (<sp-top-nav-item>): Default slot; individual clickable navigation links
  • Label: Optional property to set an aria-label for the top navigation
  • Selection indicator: A visual indicator that animates to the selected item
  • Divider: Optional <div> divider that acts as the track for the selection indicator

Options

Default 
<sp-top-nav>
    <sp-top-nav-item href="#">Site Name</sp-top-nav-item>
    <sp-top-nav-item href="#page-1" style="margin-inline-start: auto;">
        Page 1
    </sp-top-nav-item>
    <sp-top-nav-item href="#page-2">Page 2</sp-top-nav-item>
    <sp-top-nav-item href="#page-3">Page 3</sp-top-nav-item>
    <sp-top-nav-item href="#page-4">Page with really long name</sp-top-nav-item>
</sp-top-nav>
 With action menu integration

Other web components, like action menus and/or buttons, can be included in the <sp-top-nav> slots in order to extend functionality.

<sp-top-nav>
    <sp-top-nav-item href="#">Site Name</sp-top-nav-item>
    <sp-top-nav-item href="#page-1" style="margin-inline-start: auto;">
        Page 1
    </sp-top-nav-item>
    <sp-top-nav-item href="#page-2">Page 2</sp-top-nav-item>
    <sp-top-nav-item href="#page-3">Page 3</sp-top-nav-item>
    <sp-action-menu
        label="Account"
        placement="bottom-end"
        style="margin-inline-start: auto;"
        quiet
    >
        <sp-menu-item>Account settings</sp-menu-item>
        <sp-menu-item>My profile</sp-menu-item>
        <sp-menu-divider></sp-menu-divider>
        <sp-menu-item>Help</sp-menu-item>
        <sp-menu-item>Sign out</sp-menu-item>
    </sp-action-menu>
</sp-top-nav>
 With default selection

Setting the selected property to a URL that matches a top navigation item's resolved href value will render that item selected by default. The selected value must match the fully resolved URL, not just the href attribute value.

For demonstration purposes only, the href value of the selected top nav item is hardcoded, as opposed to being a dynamic href or a jump link.

<sp-top-nav
    selected="https://opensource.adobe.com/spectrum-web-components/components/top-nav/"
>
    <sp-top-nav-item href="#">Site Name</sp-top-nav-item>
    <sp-top-nav-item href="#home" style="margin-inline-start: auto;">
        Home
    </sp-top-nav-item>
    <sp-top-nav-item href="#services">Services</sp-top-nav-item>
    <sp-top-nav-item
        href="https://opensource.adobe.com/spectrum-web-components/components/top-nav/"
        selected
    >
        About
    </sp-top-nav-item>
</sp-top-nav>
 Ignoring URL parts for selection

If implementations wish to ignore certain URL parts when matching for selection, the ignore-url-parts can be defined with a space-separated list. Currently supported values are hash and search, which will remove the #hash and ?search=value respectively.

<sp-top-nav ignore-url-parts="search hash">
    <sp-top-nav-item href="/page1">Page 1</sp-top-nav-item>
    <sp-top-nav-item href="/page2">Page 2</sp-top-nav-item>
</sp-top-nav>
 Quiet variant

The quiet property renders the top navigation component without the bottom border.

<sp-top-nav quiet>
    <sp-top-nav-item href="#">Home</sp-top-nav-item>
    <sp-top-nav-item href="/products">Products</sp-top-nav-item>
</sp-top-nav>

Sizes

Small 
<sp-top-nav size="s">
    <sp-top-nav-item href="#">Site Name</sp-top-nav-item>
    <sp-top-nav-item href="#page-1" style="margin-inline-start: auto;">
        Page 1
    </sp-top-nav-item>
    <sp-top-nav-item href="#page-2">Page 2</sp-top-nav-item>
    <sp-top-nav-item href="#page-3">Page 3</sp-top-nav-item>
    <sp-top-nav-item href="#page-4">Page with really long name</sp-top-nav-item>
</sp-top-nav>
 Medium 
<sp-top-nav size="m">
    <sp-top-nav-item href="#">Site Name</sp-top-nav-item>
    <sp-top-nav-item href="#page-1" style="margin-inline-start: auto;">
        Page 1
    </sp-top-nav-item>
    <sp-top-nav-item href="#page-2">Page 2</sp-top-nav-item>
    <sp-top-nav-item href="#page-3">Page 3</sp-top-nav-item>
    <sp-top-nav-item href="#page-4">Page with really long name</sp-top-nav-item>
</sp-top-nav>
 Large 
<sp-top-nav size="l">
    <sp-top-nav-item href="#">Site Name</sp-top-nav-item>
    <sp-top-nav-item href="#page-1" style="margin-inline-start: auto;">
        Page 1
    </sp-top-nav-item>
    <sp-top-nav-item href="#page-2">Page 2</sp-top-nav-item>
    <sp-top-nav-item href="#page-3">Page 3</sp-top-nav-item>
    <sp-top-nav-item href="#page-4">Page with really long name</sp-top-nav-item>
</sp-top-nav>
 Extra large 
<sp-top-nav size="xl">
    <sp-top-nav-item href="#">Site Name</sp-top-nav-item>
    <sp-top-nav-item href="#page-1" style="margin-inline-start: auto;">
        Page 1
    </sp-top-nav-item>
    <sp-top-nav-item href="#page-2">Page 2</sp-top-nav-item>
    <sp-top-nav-item href="#page-3">Page 3</sp-top-nav-item>
    <sp-top-nav-item href="#page-4">Page with really long name</sp-top-nav-item>
</sp-top-nav>

Behaviors

  • Items are automatically selected based on the current window.location.href
  • Use ignore-url-parts to ignore hash fragments or search parameters when matching
  • Items can be programmatically selected via the selected property
  • The selection indicator automatically resizes based on item content changes
  • Items can be positioned with CSS using CSS via the style attribute set on <sp-top-nav-item> elements (e.g., margin-inline-start: auto)

Accessibility

ARIA attributes

  • role="navigation" is automatically applied to the top nav container
  • The label property set on <sp-top-nav> will set an aria-label for screen readers
  • Selected items receive aria-current="page"

Keyboard interaction

  • Tab should move focus between all navigation items in a logical tab order
  • Enter selects navigation items

Best practices

  • Always provide a label for the navigation container.
  • Use semantic href values that match actual page URLs for automatic selection.
  • Provide meaningful text content for navigation items - avoid icon-only items without labels.

Attributes and Properties

Property Attribute Type Default Description ignoreURLParts ignore-url-parts string '' A space separated list of part of the URL to ignore when matching for the "selected" Top Nav Item. Currently supported values are `hash` and `search`, which will remove the `#hash` and `?search=value` respectively. label label string '' quiet quiet boolean false The Top Nav is displayed without a border. selected selected string | undefined selectionIndicatorStyle selectionIndicatorStyle noSelectionStyle

Slots

Name Description default slot Nav Items to display as a group

Patch Changes

  • Updated dependencies [8da375b]:
    • @spectrum-web-components/tabs@1.7.0
    • @spectrum-web-components/base@1.7.0
    • @spectrum-web-components/shared@1.7.0

1.6.0

Patch Changes

  • Updated dependencies [a9727d2]:
    • @spectrum-web-components/tabs@1.6.0
    • @spectrum-web-components/base@1.6.0
    • @spectrum-web-components/shared@1.6.0

1.5.0

Patch Changes

  • Updated dependencies [c7efe31]:
    • @spectrum-web-components/tabs@1.5.0
    • @spectrum-web-components/base@1.5.0
    • @spectrum-web-components/shared@1.5.0

1.4.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/tabs@1.4.0
    • @spectrum-web-components/base@1.4.0
    • @spectrum-web-components/shared@1.4.0

1.3.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/tabs@1.3.0
    • @spectrum-web-components/base@1.3.0
    • @spectrum-web-components/shared@1.3.0

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

1.2.0 (2025-02-27)

Note: Version bump only for package @spectrum-web-components/top-nav

1.1.2 (2025-02-12)

Note: Version bump only for package @spectrum-web-components/top-nav

1.1.1 (2025-01-29)

Note: Version bump only for package @spectrum-web-components/top-nav

1.1.0 (2025-01-29)

Note: Version bump only for package @spectrum-web-components/top-nav

1.0.3 (2024-12-09)

Note: Version bump only for package @spectrum-web-components/top-nav

1.0.1 (2024-11-11)

Note: Version bump only for package @spectrum-web-components/top-nav

1.0.0 (2024-10-31)

Note: Version bump only for package @spectrum-web-components/top-nav

0.49.0 (2024-10-15)

Note: Version bump only for package @spectrum-web-components/top-nav

0.48.1 (2024-10-01)

Note: Version bump only for package @spectrum-web-components/top-nav

0.48.0 (2024-09-17)

Note: Version bump only for package @spectrum-web-components/top-nav

0.47.2 (2024-09-03)

Note: Version bump only for package @spectrum-web-components/top-nav

0.47.1 (2024-08-27)

Note: Version bump only for package @spectrum-web-components/top-nav

0.47.0 (2024-08-20)

Features

  • breadcrumbs: add Breadcrumbs component (#4578) (acd4b5e)

0.46.0 (2024-08-08)

Note: Version bump only for package @spectrum-web-components/top-nav

0.45.0 (2024-07-30)

Note: Version bump only for package @spectrum-web-components/top-nav

0.44.0 (2024-07-15)

Note: Version bump only for package @spectrum-web-components/top-nav

0.43.0 (2024-06-11)

Note: Version bump only for package @spectrum-web-components/top-nav

0.42.5 (2024-05-24)

Note: Version bump only for package @spectrum-web-components/top-nav

0.42.4 (2024-05-14)

Note: Version bump only for package @spectrum-web-components/top-nav

0.42.3 (2024-05-01)

Note: Version bump only for package @spectrum-web-components/top-nav

0.42.2 (2024-04-03)

Note: Version bump only for package @spectrum-web-components/top-nav

0.42.1 (2024-04-02)

Bug Fixes

  • shared: ensure the "updateComplete" in Focusable is stable (885b4a5)

0.42.0 (2024-03-19)

Note: Version bump only for package @spectrum-web-components/top-nav

0.41.2 (2024-03-05)

Note: Version bump only for package @spectrum-web-components/top-nav

0.41.1 (2024-02-22)

Bug Fixes

  • top-nav: focus loupe on :focus-visible only (50d6870)

0.41.0 (2024-02-13)

Note: Version bump only for package @spectrum-web-components/top-nav

0.40.5 (2024-02-05)

Note: Version bump only for package @spectrum-web-components/top-nav

0.40.4 (2024-01-29)

Note: Version bump only for package @spectrum-web-components/top-nav

0.40.3 (2024-01-11)

Bug Fixes

  • top-nav: allow consumers to "ignore-url-parts" or "search" or "hash" (#3923) (83bf70b)

0.40.2 (2023-12-18)

Note: Version bump only for package @spectrum-web-components/top-nav

0.40.1 (2023-12-05)

Note: Version bump only for package @spectrum-web-components/top-nav

0.40.0 (2023-11-16)

Note: Version bump only for package @spectrum-web-components/top-nav

0.39.4 (2023-11-02)

Bug Fixes

  • top-nav: default to role="navigation", sprout aria-label when "label" applied (bbcea4a)

0.39.3 (2023-10-18)

Note: Version bump only for package @spectrum-web-components/top-nav

0.39.2 (2023-10-13)

Note: Version bump only for package @spectrum-web-components/top-nav

0.39.1 (2023-10-06)

Note: Version bump only for package @spectrum-web-components/top-nav

0.39.0 (2023-09-25)

Note: Version bump only for package @spectrum-web-components/top-nav

0.38.0 (2023-09-05)

Note: Version bump only for package @spectrum-web-components/top-nav

0.37.0 (2023-08-18)

Note: Version bump only for package @spectrum-web-components/top-nav

0.36.0 (2023-08-18)

Note: Version bump only for package @spectrum-web-components/top-nav

0.35.0 (2023-07-31)

Note: Version bump only for package @spectrum-web-components/top-nav

0.34.0 (2023-07-11)

Features

  • tabs,top-nav: use Core Tokens (c6ba355)

0.33.2 (2023-06-14)

Note: Version bump only for package @spectrum-web-components/top-nav

0.33.0 (2023-06-08)

Note: Version bump only for package @spectrum-web-components/top-nav

0.32.0 (2023-06-01)

Note: Version bump only for package @spectrum-web-components/top-nav

0.31.0 (2023-05-17)

Note: Version bump only for package @spectrum-web-components/top-nav

0.30.0 (2023-05-03)

Bug Fixes

  • add tabs sizes to TopNav (159bc89)
  • correct @element jsDoc listing across library (c97a632)
  • include default export in the "exports" fields (f32407d)
  • include the "types" entry in package.json files (b432f59)
  • lint away debugger statements (34a498e)
  • proper overflow rtl support (9b1c9d4)
  • remove <sp-menu> usage where deprecated (387db3b)
  • tabs: add "tablist" part to manage list styles (bbf8074)
  • tabs: correct indicator size by scaling from 100px (a3fb68b)
  • top-nav: ensure focus state in all contexts (6de83be)
  • top-nav: initialize nav with an undefined selection (3473f63)
  • top-nav: match indicator management strategy from Tabs (ecc76a0)
  • top-nav: minor edits to description, typos (bc2ee48)
  • top-nav: prototype top-nav pattern (9708f6f)
  • update indicator animation for loading and content direction (f607f8b)
  • use icons without "size" values (3fc7c91)
  • use typescript@^4.5 for "native" document.fonts typings (a3e4aea)

Features

  • adopt DNA@7 base Spectrum CSS (e08cafd)
  • include all Dev Mode files in side effects (f70817c)
  • sets action-menu quiet to false by default, fixes #3040 (8414cab)
  • shared pkg versions, devmode define warning, registry-conflicts docs (6e49565)
  • tabs: add sp-tab-panel element (b17d276)
  • use latest exports specification (a7ecf4b)

Performance Improvements

  • reduce render cycles when managing "dir" attribute (7b28309)

0.7.2 (2023-04-24)

Note: Version bump only for package @spectrum-web-components/top-nav

0.7.1 (2023-04-05)

Performance Improvements

  • reduce render cycles when managing "dir" attribute (7b28309)

0.7.0 (2023-03-22)

Bug Fixes

  • add tabs sizes to TopNav (159bc89)
  • proper overflow rtl support (9b1c9d4)

Features

  • sets action-menu quiet to false by default, fixes #3040 (8414cab)

0.6.13 (2023-03-08)

Note: Version bump only for package @spectrum-web-components/top-nav

0.6.12 (2023-02-21)

Note: Version bump only for package @spectrum-web-components/top-nav

0.6.11 (2023-02-08)

Bug Fixes

  • tabs: correct indicator size by scaling from 100px (a3fb68b)

0.6.10 (2023-01-23)

Note: Version bump only for package @spectrum-web-components/top-nav

0.6.9 (2023-01-09)

Note: Version bump only for package @spectrum-web-components/top-nav

0.6.8 (2022-12-08)

Note: Version bump only for package @spectrum-web-components/top-nav

0.6.7 (2022-11-21)

Note: Version bump only for package @spectrum-web-components/top-nav

0.6.6 (2022-11-14)

Note: Version bump only for package @spectrum-web-components/top-nav

0.6.5 (2022-10-28)

Note: Version bump only for package @spectrum-web-components/top-nav

0.6.4 (2022-10-17)

Note: Version bump only for package @spectrum-web-components/top-nav

0.6.3 (2022-10-10)

Note: Version bump only for package @spectrum-web-components/top-nav

0.6.2 (2022-09-14)

Note: Version bump only for package @spectrum-web-components/top-nav

0.6.1 (2022-08-24)

Bug Fixes

  • top-nav: match indicator management strategy from Tabs (ecc76a0)

0.6.0 (2022-08-09)

Features

  • include all Dev Mode files in side effects (f70817c)

0.5.15 (2022-08-04)

Bug Fixes

  • tabs: add "tablist" part to manage list styles (bbf8074)

0.5.14 (2022-07-18)

Note: Version bump only for package @spectrum-web-components/top-nav

0.5.13 (2022-06-29)

Note: Version bump only for package @spectrum-web-components/top-nav

0.5.12 (2022-06-07)

Note: Version bump only for package @spectrum-web-components/top-nav

0.5.11 (2022-05-27)

Note: Version bump only for package @spectrum-web-components/top-nav

0.5.10 (2022-05-12)

Note: Version bump only for package @spectrum-web-components/top-nav

0.5.9 (2022-04-21)

Note: Version bump only for package @spectrum-web-components/top-nav

0.5.8 (2022-03-30)

Note: Version bump only for package @spectrum-web-components/top-nav

0.5.7 (2022-03-08)

Note: Version bump only for package @spectrum-web-components/top-nav

0.5.6 (2022-03-04)

Note: Version bump only for package @spectrum-web-components/top-nav

0.5.5 (2022-02-22)

Note: Version bump only for package @spectrum-web-components/top-nav

0.5.4 (2022-02-02)

Note: Version bump only for package @spectrum-web-components/top-nav

0.5.3 (2022-01-26)

Bug Fixes

  • top-nav: ensure focus state in all contexts (6de83be)

0.5.2 (2022-01-07)

Note: Version bump only for package @spectrum-web-components/top-nav

0.5.1 (2021-12-13)

Bug Fixes

  • use typescript@^4.5 for "native" document.fonts typings (a3e4aea)

0.5.0 (2021-11-08)

Note: Version bump only for package @spectrum-web-components/top-nav

0.4.1 (2021-11-08)

Note: Version bump only for package @spectrum-web-components/top-nav

0.4.0 (2021-11-02)

Features

  • adopt DNA@7 base Spectrum CSS (e08cafd)

0.3.10 (2021-10-12)

Note: Version bump only for package @spectrum-web-components/top-nav

0.3.9 (2021-09-20)

Note: Version bump only for package @spectrum-web-components/top-nav

0.3.8 (2021-09-13)

Note: Version bump only for package @spectrum-web-components/top-nav

0.3.7 (2021-08-24)

Bug Fixes

  • correct @element jsDoc listing across library (c97a632)

0.3.6 (2021-08-03)

Note: Version bump only for package @spectrum-web-components/top-nav

0.3.5 (2021-07-22)

Note: Version bump only for package @spectrum-web-components/top-nav

0.3.4 (2021-07-01)

Bug Fixes

  • update indicator animation for loading and content direction (f607f8b)

0.3.3 (2021-06-16)

Note: Version bump only for package @spectrum-web-components/top-nav

0.3.2 (2021-06-07)

Bug Fixes

  • lint away debugger statements (34a498e)

0.3.1 (2021-05-25)

Note: Version bump only for package @spectrum-web-components/top-nav

0.3.0 (2021-05-24)

Features

  • tabs: add sp-tab-panel element (b17d276)

0.2.6 (2021-05-12)

Note: Version bump only for package @spectrum-web-components/top-nav

0.2.5 (2021-04-09)

Note: Version bump only for package @spectrum-web-components/top-nav

0.2.4 (2021-03-29)

Note: Version bump only for package @spectrum-web-components/top-nav

0.2.3 (2021-03-22)

Note: Version bump only for package @spectrum-web-components/top-nav

0.2.2 (2021-03-22)

Bug Fixes

  • remove <sp-menu> usage where deprecated (387db3b)

0.2.1 (2021-03-05)

Note: Version bump only for package @spectrum-web-components/top-nav

0.2.0 (2021-03-04)

Features

  • use latest exports specification (a7ecf4b)

0.1.4 (2021-02-11)

Note: Version bump only for package @spectrum-web-components/top-nav

0.1.3 (2021-02-02)

Note: Version bump only for package @spectrum-web-components/top-nav

0.1.2 (2021-01-28)

Note: Version bump only for package @spectrum-web-components/top-nav

0.1.1 (2021-01-21)

Bug Fixes

  • top-nav: minor edits to description, typos (bc2ee48)
  • include the "types" entry in package.json files (b432f59)
  • use icons without "size" values (3fc7c91)
  • top-nav: initialize nav with an undefined selection (3473f63)

0.1.0 (2021-01-13)

Bug Fixes

  • include the "types" entry in package.json files (b432f59)
  • use icons without "size" values (3fc7c91)
  • top-nav: initialize nav with an undefined selection (3473f63)

0.0.5 (2020-10-12)

Note: Version bump only for package @spectrum-web-components/top-nav

0.0.4 (2020-10-12)

Bug Fixes

  • include default export in the "exports" fields (f32407d)

0.0.3 (2020-09-25)

Note: Version bump only for package @spectrum-web-components/top-nav

0.0.2 (2020-09-14)

Bug Fixes

  • top-nav: prototype top-nav pattern (9708f6f)