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
Side navigation allows users to locate information and features within the UI.
4
4
It can be used for either hierarchical or flat navigation, and gives the ability
@@ -7,37 +7,67 @@ prioritize content or features based on your users’ needs in a way that
7
7
maintains clear, persistent visibility. Use side navigation within the context
8
8
of larger elements and mechanisms within the app frame.
9
9
10
-
`<sp-sidenav>` elements accept both `<sp-sidenav-item>` and `<sp-sidenav-heading>` elements as children in order to construct a hierarchy of navigation elements. [`<sp-sidenav-item>`](./components/sidenav-item) elements will place themselves as a togglable child of their `<sp-sidenav>` element parent. `<sp-sidenav-heading>` elements will create visible structure by grouping their child `<sp-sidenav-item>` children under a non-interactive heading.
10
+
`<sp-sidenav>` elements accept both `<sp-sidenav-item>` and `<sp-sidenav-heading>` elements as children in order to construct a hierarchy of navigation elements. [`<sp-sidenav-item>`](/components/sidenav-item/) elements will place themselves as a togglable child of their `<sp-sidenav>` element parent. [`<sp-sidenav-heading>`](/components/sidenav-heading/) elements will create visible structure by grouping their `<sp-sidenav-item>` children under a non-interactive heading.
11
+
12
+
[View the design documentation for this component.](https://spectrum.adobe.com/page/side-navigation/)
11
13
12
14
### Usage
13
15
14
16
[](https://www.npmjs.com/package/@spectrum-web-components/sidenav)
15
17
[](https://bundlephobia.com/result?p=@spectrum-web-components/sidenav)
16
18
[](https://stackblitz.com/edit/vitejs-vite-q3w6kjxv)
17
19
18
-
```
20
+
```bash
19
21
yarn add @spectrum-web-components/sidenav
20
22
```
21
23
22
24
Import the side effectful registration of `<sp-sidenav>`, `<sp-sidenav-heading>`, or `<sp-sidenav-item>` via:
Make sure to use the right option for the context and user needs. Don’t mix behavior, styles, or variations together in a single navigation menu. Follow these guidelines:
67
+
68
+
- When navigation is simple, use the single level side navigation.
69
+
- When navigation is simple but categorical, use the single level side navigation with headers.
70
+
- When navigation is expansive, hierarchical, and/or you need progressive disclosure in the menu behavior, use the multi-level side navigation. Up to three levels of navigation are supported.
<sp-tabvalue="icon-single">Single-level with icons</sp-tab>
114
+
<sp-tab-panelvalue="icon-single">
112
115
113
-
## Icon
116
+
In single-level side navigation, do not mix icon usage between side nav items. Either all side nav items have icons, or no items have icons. In cases where the navigation content might be user-generated, stick to text-only navigation items.
114
117
115
118
```html
116
119
<sp-sidenav>
117
120
<sp-sidenav-itemvalue="Section Title 1"label="Section Title 1">
118
121
<sp-icon-starslot="icon"></sp-icon-star>
119
122
</sp-sidenav-item>
120
-
<sp-sidenav-itemvalue="Section Title 2"label="Section Title 2">
123
+
<sp-sidenav-itemvalue="Section Title 2"label="Section Title 2"expanded>
121
124
<sp-icon-starslot="icon"></sp-icon-star>
122
125
</sp-sidenav-item>
123
-
<sp-sidenav-itemvalue="Section Title 3"label="Section Title 3">
126
+
<sp-sidenav-itemvalue="Section Title 3"label="Section Title 3"expanded>
124
127
<sp-icon-starslot="icon"></sp-icon-star>
125
128
</sp-sidenav-item>
126
129
</sp-sidenav>
127
130
```
128
131
129
-
## Heading
132
+
</sp-tab-panel>
133
+
<sp-tabvalue="headings">With headings</sp-tab>
134
+
<sp-tab-panelvalue="headings">
135
+
136
+
Use headings in single level side navigation when it's beneficial to group navigation items into categories. The headings are not interactive. If items don’t fall into a category, place them at the top. When using the heading variation, an entire category should either all have icons or all be text-only.
137
+
138
+
Although headings can be used in multi-level side navigation, they can only be used as first-level items, and are not to be nested.
<sp-tabvalue="icon-multi">Multi-level with icons</sp-tab>
190
+
<sp-tab-panelvalue="icon-multi">
191
+
192
+
In multi-level side navigation, icon and text-only navigation items can be used in combination, but only the first-level items can have icons to maintain visual clarity and hierarchy. Icons only appear on first-level items, and sublevels (second and third) should not include icons. In cases where the navigation content might be user-generated, stick to text-only navigation items.
193
+
194
+
#### Multi-level side navigation icon usage
195
+
196
+
- All icons: all items have icons
197
+
- No icons: no items have icons
198
+
- Mixed icons: only first-level items have icons; second and third-level items do not
199
+
200
+
```html
201
+
<sp-sidenav>
202
+
<sp-sidenav-itemvalue="Section Title 1"label="Section Title 1">
203
+
<sp-icon-starslot="icon"></sp-icon-star>
204
+
<sp-sidenav-item
205
+
value="Typography"
206
+
label="Typography"
207
+
></sp-sidenav-item>
208
+
</sp-sidenav-item>
209
+
<sp-sidenav-itemvalue="Section Title 2"label="Section Title 2"expanded>
210
+
<sp-icon-starslot="icon"></sp-icon-star>
211
+
<sp-sidenav-item
212
+
value="Iconography"
213
+
label="Iconography"
214
+
></sp-sidenav-item>
215
+
</sp-sidenav-item>
216
+
<sp-sidenav-itemvalue="Section Title 3"label="Section Title 3"expanded>
When an side navigation item is programmatically selected in `variant="multilevel"`, all of its parent items automatically expand to reveal the selection path.
232
+
233
+
### Accessibility
234
+
235
+
When the `manage-tab-index` attribute is set on an `<sp-sidenav>` element, it will present its `<sp-sidenav-item>` children with a single tab-stop. This will leave items beyond the selected item (or when there is no focusable selected item), accessible via the up and down arrow keys. Items with expanded children that aren't selected lose focus when `manage-tab-index` is active.
236
+
237
+
#### Roles and ARIA attributes
238
+
239
+
-`<sp-sidenav>` renders a `<nav>` tag and implicitly sets `role="navigation"`
240
+
- Optional `aria-label` is available for further identification
241
+
- Individual items use `role="listitem"` automatically
242
+
- Nested list containers (i.e. `<div>` tags) use `role="list"`
243
+
- Nested item containers use `aria-labelledby` referencing their parent item's `id`
244
+
-`aria-expanded="true/false"` indicates expand/collapse state for parent items
245
+
-`aria-controls` on parent items is set to the `id` of their child `role="list"` containers when expanded
246
+
-`aria-current="page"` indicates the currently selected item when it has an `href`
247
+
- When the `<sp-sidenav>` includes the `disabled` property, the entire component receives `tabindex="-1"`
248
+
-`aria-hidden="true"` is applied to all decorative icons
249
+
250
+
#### Keyboard interaction
147
251
148
-
When the `manage-tab-index` attribute is set on an `sp-sidenav` element then it will presents its child `sp-sidenav-item` children with a single tab-stop. This will leave items beyond the selected item, or first when there is no focusable selected item, will be accessibile via the up and down arrow keys.
252
+
-`Tab` and `Shift + Tab` moves focus into or out of the side nav
253
+
- If `manage-tab-index` is enabled, the up and down arrow keys will shift focus between all visible sidenav items
254
+
-`Enter` selects a side nav item or toggles expansion for parent items
`<sp-sidenav-heading>` elements will create visible structure by grouping their child `<sp-sidenav-item>` children under a non-interactive heading. Headings are used at the first level of navigation, and should not be used in any subsequent navigation level.
4
+
5
+
### Usage
6
+
7
+
[](https://www.npmjs.com/package/@spectrum-web-components/sidenav)
8
+
[](https://bundlephobia.com/result?p=@spectrum-web-components/sidenav)
9
+
10
+
```bash
11
+
yarn add @spectrum-web-components/sidenav
12
+
```
13
+
14
+
Import the side effectful registration of `<sp-sidenav-heading>` via:
-**Default slot**: children `<sp-sidenav-item>` elements will be categorized under the heading element
30
+
31
+
### Options
32
+
33
+
<sp-tabsselected="single-level"autolabel="Side nav heading options">
34
+
<sp-tabvalue="single-level">Single-level with headings</sp-tab>
35
+
<sp-tab-panelvalue="single-level">
36
+
37
+
Use a single level side navigation with headings when needing to group navigation items into categories. Headings are not interactive.
38
+
39
+
```html
40
+
<sp-sidenav>
41
+
<sp-sidenav-headinglabel="Docs heading">
42
+
<sp-sidenav-item
43
+
value="new-docs"
44
+
label="New docs"
45
+
href="/components/sidenav"
46
+
></sp-sidenav-item>
47
+
<sp-sidenav-item
48
+
value="old-docs"
49
+
label="Old docs"
50
+
href="/components/sidenav"
51
+
></sp-sidenav-item>
52
+
</sp-sidenav-heading>
53
+
</sp-sidenav>
54
+
```
55
+
56
+
</sp-tab-panel>
57
+
<sp-tabvalue="multi-level">Multi-level with headings</sp-tab>
58
+
<sp-tab-panelvalue="multi-level">
59
+
60
+
In multi-level side navigation, headings can only be used at the first level of navigation. Do not nest headings within second or third level side nav items.
0 commit comments