You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
An `<sp-sidenav-item>`stands as both a child item of an `<sp-sidenav>` element, as well as a parent for further subdivisions of that navigation. An `<sp-sidenav-item>` with further `<sp-sidenav-item>` children will count as a toggle for the visibility of this next level of navigation items, while also updating the parent `<sp-sidenav>` element to its value when selected.
3
+
An `<sp-sidenav-item>`can act as both a child item of an `<sp-sidenav>` element, as well as a parent for further subdivisions of that navigation. An `<sp-sidenav-item>` with further `<sp-sidenav-item>` children will count as a toggle for the visibility of the next level of navigation items, while also updating the parent `<sp-sidenav>` element to its value when selected.
4
4
5
5
### Usage
6
6
7
7
[](https://www.npmjs.com/package/@spectrum-web-components/sidenav)
8
8
[](https://bundlephobia.com/result?p=@spectrum-web-components/sidenav)
9
9
10
-
```
10
+
```bash
11
11
yarn add @spectrum-web-components/sidenav
12
12
```
13
13
14
14
Import the side effectful registration of `<sp-sidenav-item>` via:
-**Value**: Unique identifier; required for selection changes via the `sidenav-select` event
30
+
-**href** (optional): When defined, renders the side nav item as an anchor link
31
+
-**Default slot**: Nested `sp-sidenav-items`
32
+
33
+
### Options
34
+
35
+
<sp-tabsselected="default"autolabel="Side nav item options">
36
+
<sp-tabvalue="default">Default</sp-tab>
37
+
<sp-tab-panelvalue="default">
38
+
39
+
Most often, the default side nav item includes an `href` to navigate users to a new page or section.
27
40
28
41
```html
29
42
<sp-sidenav>
30
43
<sp-sidenav-item
31
-
value="Docs"
32
-
label="Docs"
44
+
value="pixar"
45
+
label="Pixar movies"
33
46
href="/components/sidenav"
34
47
></sp-sidenav-item>
35
48
</sp-sidenav>
36
49
```
37
50
38
-
## Multi-level
51
+
</sp-tab-panel>
52
+
<sp-tabvalue="multi-level">Multi-level</sp-tab>
53
+
<sp-tab-panelvalue="multi-level">
54
+
55
+
To create a multi-level navigation, set the parent `<sp-sidenav>` to `variant="multilevel"` and nest `sp-sidenav-item` elements inside each other. Parent `sp-sidenav-item` elements that contain children can use the `expanded` attribute to show and hide their nested items. Each `sp-sidenav-item` with nested children acts as both a selectable navigation item (with its own value) and a toggle for expanding/collapsing its children.
39
56
40
57
```html
41
58
<sp-sidenavvariant="multilevel">
@@ -54,12 +71,232 @@ import { SidenavItem } from '@spectrum-web-components/sidenav';
54
71
</sp-sidenav-itm>
55
72
```
56
73
57
-
## Icon
74
+
</sp-tab-panel>
75
+
<sp-tabvalue="icons">Accommodating icons</sp-tab>
76
+
<sp-tab-panelvalue="icons">
77
+
78
+
Icons can be displayed in first-level items of any type of side navigation (single level or multi-level). Use icons only when absolutely necessary: when they add essential value and have a strong association with the text. Never use icons just as decoration.
58
79
59
80
```html
60
81
<sp-sidenav>
61
-
<sp-sidenav-itemvalue="Section Title 1"label="Section Title 1">
82
+
<sp-sidenav-itemvalue="star"label="Starred">
62
83
<sp-icon-starslot="icon"></sp-icon-star>
63
84
</sp-sidenav-item>
85
+
<sp-sidenav-itemvalue="home"label="Home">
86
+
<sp-icon-homeslot="icon"></sp-icon-home>
87
+
</sp-sidenav-item>
88
+
</sp-sidenav>
89
+
```
90
+
91
+
</sp-tab-panel>
92
+
<sp-tabvalue="target">Target</sp-tab>
93
+
<sp-tab-panelvalue="target">
94
+
95
+
The `target` property specifies where to display the linked URL, such as in a new tab (`_blank`), parent frame (`_parent`), same frame (`_self`), or top frame (`_top`). It only applies when the sidenav item has an `href` attribute and functions like a standard HTML anchor link.
96
+
97
+
```html
98
+
<sp-sidenav>
99
+
<sp-sidenav-item
100
+
value="pixar"
101
+
label="Pixar movies"
102
+
href="/components/sidenav"
103
+
target="_blank"
104
+
></sp-sidenav-item>
105
+
</sp-sidenav>
106
+
```
107
+
108
+
</sp-tab-panel>
109
+
<sp-tabvalue="download">Download</sp-tab>
110
+
<sp-tab-panelvalue="download">
111
+
112
+
When set, the `download` property causes the browser to treat the linked URL as a downloadable file, rather than navigating to it. It works in conjunction with the `href` attribute to trigger file downloads when the sidenav item is clicked.
113
+
114
+
```html
115
+
<sp-sidenav>
116
+
<sp-sidenav-item
117
+
value="pixar"
118
+
label="Pixar movies"
119
+
href="/components/sidenav"
120
+
download
121
+
></sp-sidenav-item>
122
+
</sp-sidenav>
123
+
```
124
+
125
+
</sp-tab-panel>
126
+
<sp-tabvalue="rel">Rel</sp-tab>
127
+
<sp-tab-panelvalue="rel">
128
+
129
+
The `rel` property defines the relationship between the current page and the linked URL using space-separated link types (like `nofollow`, `noreferrer`, or `external`). It provides semantic information to browsers and search engines about the nature of the link relationship.
Setting `referrer-policy` will control how much referrer information is sent when following the link, with options ranging from no referrer (`no-referrer`) to full URL (`unsafe-url`).
147
+
148
+
```html
149
+
<sp-sidenav>
150
+
<sp-sidenav-item
151
+
value="pixar"
152
+
label="Pixar movies"
153
+
href="/components/sidenav"
154
+
referrerpolicy="no-referrer"
155
+
></sp-sidenav-item>
156
+
</sp-sidenav>
157
+
```
158
+
159
+
</sp-tab-panel>
160
+
</sp-tabs>
161
+
162
+
### States
163
+
164
+
<sp-tabsselected="disabled"autolabel="Side nav item states">
165
+
<sp-tabvalue="disabled">Disabled</sp-tab>
166
+
<sp-tab-panelvalue="disabled">
167
+
168
+
Adding the `disabled` attribute to a side nav item renders it non-interactive.
When users select an item, the `selected` attribute is applied. The `value` of the selected item will be bubbled up to the parent `sp-sidenav` to update the `value` of `sp-sidenav`.
When the side navigation item text is too long for the horizontal space available, it wraps to form another line.
271
+
272
+
For RTL (right-to-left) languages, the layout of the side navigation is mirrored. Navigation items are left-aligned and their icons are placed on the right side of the text.
273
+
274
+
When users select an `sp-sidenav-item`, the change in the `value` property of the parent side navigation element is announced. This change can be "canceled" via `event.preventDefault()`.
275
+
276
+
When `manage-tab-index` is enabled on the parent side nav, expanded parent side nav items that aren't selected lose focus to prevent focus traps.
277
+
278
+
### Accessibility
279
+
280
+
#### ARIA attributes
281
+
282
+
- Individual items use `role="listitem"` automatically
283
+
- Nested list containers (i.e. `div` tags) use `role="list"`
284
+
- Nested item containers use `aria-labelledby` referencing their parent item's `id`
285
+
-`aria-expanded="true/false"` indicates expand/collapse state for parent side nav items
286
+
-`aria-controls` on parent items is set to the `id` of their child `role="list"` containers when expanded
287
+
-`aria-current="page"` indicates the currently selected item when it has an `href`
288
+
-`aria-hidden="true"` should be applied to all decorative icons
289
+
290
+
#### Keyboard interactions
291
+
292
+
**Standard navigation:** (when parent side nav has `manage-tab-index` disabled)
293
+
294
+
-`Tab` moves focus to individual items
295
+
-`Enter` or `Space` select a focused item or toggle the expansion of any nested side nav items
296
+
297
+
**Roving `tabindex` mode** (when parent side nav has `manage-tab-index="true"`):
298
+
299
+
- The parent `sp-sidenav` component is the single tab-stop
300
+
-`Up` and `Down` arrow keys navigate between all visible side nav items
301
+
-`Home` and `End` keys jump to first/last items respectively
302
+
-`Enter` or `Space` select a focused item or toggle the expansion of any nested side nav items
0 commit comments