---
title: "Side navigation - Cloudscape Design System"
source: "https://cloudscape.design/components/side-navigation/?tabId=api"
created: 2025-11-21
description: "A list of navigational links that point to the pages within an application."
---
- [Playground](https://cloudscape.design/components/side-navigation/?tabId=playground)
- [API](https://cloudscape.design/components/side-navigation/?tabId=api)
- [Testing](https://cloudscape.design/components/side-navigation/?tabId=testing)
- [Usage](https://cloudscape.design/components/side-navigation/?tabId=usage)
## Development guidelines
All links in the component are rendered as `<a>` tags. Therefore, a click on link will modify `window.location` object. If you use a client-side routing logic in your application, you can prevent this behavior by providing an `onFollow` event handler to the navigation component. For more information on the `onFollow` event, see the `Events` section.
The component will reset user expansion state on re-render if the reference to the items array is changed between renders. To avoid this, provide the same instance of the items array for each render.
## Properties
| Name | Type | Description | Accepted values | Default | Required |
| --- | --- | --- | --- | --- | --- |
| activeHref | ``` string ``` | Specifies the `href` of the currently active link.All items within the navigation with a matching `href` are highlighted. `Sections` and `Expandable Page Groups` that contain a highlighted itemare automatically expanded, unless their definitions have the `defaultExpanded` property explicitly set to `false`. | \- | \- | ``` false ``` |
| className (deprecated) | ``` string ``` | Adds the specified classes to the root element of the component. **Deprecated**. Custom CSS is not supported. For testing and other use cases, use [data attributes](https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes). | \- | \- | ``` false ``` |
| header | ``` SideNavigationProps.Header { href: string logo?: SideNavigationProps.Logo text?: string } ``` | Controls the header that appears at the top of the navigation component. It contains the following: - `text` (string) - Specifies the header text. - `href` (string) - Specifies the `href` that the header links to. - `logo` (object) - Specifies a logo image. | \- | \- | ``` false ``` |
| id (deprecated) | ``` string ``` | Adds the specified ID to the root element of the component. **Deprecated**. The usage of the `id` attribute is reserved for internal use cases. For testing and other use cases,use [data attributes](https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes). If you mustuse the `id` attribute, consider setting it on a parent element instead. | \- | \- | ``` false ``` |
| items | ``` ReadonlyArray<SideNavigationProps.Item> ``` | Specifies the items to be displayed in the navigation.Allowed objects are: `Link`, `Divider`, `Section`, `LinkGroup` and `ExpandableLinkGroup`. You can inject extra properties (for example, an ID)in order to identify the item when it's used in an event `detail` (for more information, see the events section below). #### Link Object that represents an anchor in the navigation.Links are rendered as `<a>` tags. - `type` - `'link'`. - `text` (string) - Specifies the link text. - `href` (string) - Specifies the `href` of the link. - `external` (boolean) - Determines whether to display an external link icon next to the link.If set to `true`, an external link icon appears next to the link.The anchor also has the attributes `target="_blank"` and `rel="noopener"`.Additionally, the `activeHref` property won't be modified when a user chooses the link. - `externalIconAriaLabel` (string) - Adds an aria-label to the external icon.Note: Deprecated, use i18nStrings.externalIconAriaLabel instead. - `info` (ReactNode) - Enables you to display content next to the link. Although it is technically possible to insert any content,our UX guidelines allow only to add a Badge and/or a "New" label. #### Divider Object that represents a horizontal divider between navigation content.It contains `type`: `'divider'` only. #### Section Object that represents a section within the navigation. - `type`: `'section'`. - `text` (string) - Specifies the text to display as a title of the section. - `defaultExpanded` (boolean) - Determines whether the section should be expanded by default. Default value is `true`. - `items` (array) - Specifies the content of the section. You can use any valid item from this list.Although there is no technical limitation to the nesting level,our UX recommendation is to use only one level. #### Section Group Aggregates a set of items that are conceptually related to each other, and can be displayed under a single heading to provide further organization.You can nest sections, links, link groups and expandable link groups within a section group depending on your information architecture needs. - `type`: `'section-group'`. - `title` (string) - Specifies the text to display as a title of the section group. - `items` (array) - Specifies the content of the section header group. You can use `Section`, `Link`, `LinkGroup`, `ExpandableLinkGroup`. #### LinkGroup Object that represents a group of links. - `type`: `'link-group'`. - `text` (string) - Specifies the text of the group link. - `href` (string) - Specifies the `href` of the group link. - `info` (ReactNode) - Enables you to display content next to the link. Although it is technically possible to insert any content,our UX guidelines allow only to add a Badge and/or a "New" label. - `items` (array) - Specifies the content of the section. You can use any valid item from this list.Although there is no technical limitation to the nesting level,our UX recommendation is to use only one level. #### ExpandableLinkGroup Object that represents an expandable group of links. - `type`: `'expandable-link-group'`. - `text` (string) - Specifies the text of the group link. - `href` (string) - Specifies the `href` of the group link. - `defaultExpanded` (boolean) - Specifies whether the group should be expanded by default.If not explicitly set, the group is collapsed by default, unless one of the nested links is active. - `items` (array) - Specifies the content of the section. You can use any valid item from this list.Although there is no technical limitation to the nesting level,our UX recommendation is to use only one level. | \- | ``` [] ``` | ``` false ``` |
## Slots
## Events
| Name | Detail | Description | Cancelable |
| --- | --- | --- | --- |
| onChange | ``` SideNavigationProps.ChangeDetail { expandableParents: ReadonlyArray< \| SideNavigationProps.Section \| SideNavigationProps.ExpandableLinkGroup > expanded: boolean item: \| SideNavigationProps.Section \| SideNavigationProps.ExpandableLinkGroup } ``` | Fired when the expansion state of `Section` or `ExpandablePageGroup` items changesas a result of a user interaction. The event `detail` contains an object with information about the changed item. - `item` (object) - Specifies the item that was changed. - `expanded` (boolean) - Specifies whether the item is expanded or not. - `expandableParents` (array) - A list of parent items that have a type of `Section` or `ExpandablePageGroup`. Use this `expandableParents` array to set their expandedstate to `true` if you want your data model to keep track of the current stateof the navigation items. Note: If the expansion is a result of the activation of a nested linkupon changing the `activeHref` property, this event isn't raised. | ``` false ``` |
| onFollow | ``` SideNavigationProps.FollowDetail { external?: boolean href: string info?: React.ReactNode target?: string text?: string type?: string } ``` | Fired when an anchor is clicked without any modifier (that is, CTRL, ALT, SHIFT).The event `detail` contains a definition of the clicked item.Use this event to prevent default browser navigation (by calling `preventDefault` method)and branch your own routing. If the event is prevented the `activeHref` property won't be automatically setto the href of the clicked item so you'll have to do it yourself. | ``` true ``` |
