Navigation - Semi Design

Demos

How to import


import { Nav } from '@douyinfe/semi-ui';

Basic Usage

By passing items Parameters, you can quickly get a navigation bar.

Each navigation item includes:

itemKey: The unique identity of the navigation project (must)
text: Navigation copywriting
icon: Navigation icon

For the meaning of the parameters, see Nav.Item Or Nav.Sub

Version: >= 0.16.0

Navigation indentation is currently effective only for first-level navigation.

If the navigation project doesn't come in, icon field, then the copy will be automatically filled to the left.

Define The Head And Bottom

Developers may often define the Logo area and the put away button area, while Navigation provides such a container for developers to quickly define the navigation head and bottom, and you only need to pass in the header or Footer as required.

For footer, semi-ui extra encapsulates a pull-up feature button that developers can pass through collapseButton = true to turn on the function, but the parameter takes effect only with mode = "vertical" (Vertical navigation).

For the parameters, see Nav.Header and Nav.Footer.

Navigation currently provides two parameters to define navigation styles:style and bodyStyle, in which style The style used to define the outermost layer of the navigation component, while bodyStyle The style used to define the navigation list. (Both the navigation head and the bottom of the navigation accept their respective style Parameters).

For example, you need a navigation list to scroll, navigate the head and bottom fixed navigation components, which can be used this way:

JSX Writing

Users can use JSX to define navigation headers, navigation items, and navigation bottoms.

Use react-router like router lib

In order to use routing components such as react-router, NavItem can be wrapped in the Link or NavLink provided by the routing component to let users click NavItem to trigger the routing component. We need to customize rendering.

Use renderWrapper to customize navigation components in each navigation item. See CodeSandBox demo


import { Link } from "react-router-dom";

()=>{
    return <Nav
        renderWrapper={({ itemElement, isSubNav, isInSubNav, props }) => {
            const routerMap = {
                Home: "/",
                About: "/about",
                Dashboard: "/dashboard",
                "Nothing Here": "/nothing-here"
            };
            return (
                <Link
                    style={{ textDecoration: "none" }}
                    to={routerMap[props.itemKey]}
                >
                    {itemElement}
                </Link>
            );
        }}
        items={[
            { itemKey: "Home", text: "Home" },
            { itemKey: "About", text: "About" },
            {
                text: "Sub",

                itemKey: "Sub",
                items: ["Dashboard", "Nothing Here"]
            }
        ]}
    ></Nav>;
};

Navigation currently offers navigation in two directions:

Vertical (default)
Horizontal

You can pass mode = "vertical" (default) or mode = "horizontal" to control.

In particular, there are some functions (parameters) only in mode = "vertical" effective:

isCollapsed (Navigation put away to the side)
defaultOpenKeys | openKeys (Specifies the default and controlled array of expanded subnavigation items key, which is valid only in mode = "vertical"and isCollapsed = false)
collapseButton of Footer

Vertical Direction

Horizontal Direction

import React from 'react'; import { Nav, Avatar, Dropdown } from '@douyinfe/semi-ui'; import { IconStar, IconUser, IconUserGroup, IconSetting, IconEdit } from '@douyinfe/semi-icons'; class NavApp extends React.Component { render() { return ( <div style={{ width: '100%' }}> <Nav mode={'horizontal'} items={[ { itemKey: 'user', text: 'User Management', icon: <IconUser /> }, { itemKey: 'union', text: 'Union Center', icon: <IconStar /> }, { itemKey: 'approve-management', text: 'Approval Management', icon: <IconEdit />, items: [ 'Check-in Review', { itemKey: 'operation-management', text: 'Operations Management', items: [ 'Personnel Management', 'Personnel Change' ] } ] }, { text: 'Task Platform', icon: <IconSetting />, itemKey: 'job', items: ['Task Management', 'User Task Query'], }, ]} onSelect={key => console.log(key)} header={{ logo: <img src="https://sf6-cdn-tos.douyinstatic.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/webcast_logo.svg" />, text: 'Live Platform' }} footer={ <Dropdown position="bottomRight" render={ <Dropdown.Menu> <Dropdown.Item>Detail</Dropdown.Item> <Dropdown.Item>Quit</Dropdown.Item> </Dropdown.Menu> } > <Avatar size="small" color='light-blue' style={{ margin: 4 }}>BD</Avatar> <span>Bytedancer</span> </Dropdown> } /> </div> ); } }

Horizontal Plus Vertical

The general platform design will adopt the mode of horizontal and vertical navigation. Here is a common example.

import React from 'react'; import { Nav, Avatar, Dropdown, Select, Button } from '@douyinfe/semi-ui'; import { IconStar, IconUser, IconUserGroup, IconSetting, IconEdit, IconLanguage } from '@douyinfe/semi-icons'; class NavApp extends React.Component { constructor() { this.items = [ { itemKey: 'user', text: 'User Management', icon: <IconUser /> }, { itemKey: 'union', text: 'Union Center', icon: <IconStar /> }, { itemKey: 'union-management', text: 'Union Management', icon: <IconUserGroup />, items: ['Announcement Settings', 'Union Query', 'Entry Information'] }, { itemKey: 'approve-management', text: 'Approval Management', icon: <IconEdit />, items: [ 'Check-in Review', { itemKey: 'operation-management', text: 'Operations Management', items: [ 'Personnel Management', 'Personnel Change' ] } ] }, { text: 'Task Platform', icon: <IconSetting />, itemKey: 'job', items: ['Task Management', 'User Task Query'], }, ]; this.renderHorizontal = this.renderHorizontal.bind(this); this.renderVertical = this.renderVertical.bind(this); } renderHorizontal() { return ( <Nav mode={'horizontal'} onSelect={key => console.log(key)} header={{ logo: <img src="https://sf6-cdn-tos.douyinstatic.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/webcast_logo.svg" />, text: 'Live Platform' }} footer={ <> <Select defaultValue='English' style={{ width: 120, marginRight: 10 }} insetLabel={<IconLanguage />}> <Select.Option value='Chinese'>中文</Select.Option> <Select.Option value='English'>English</Select.Option> <Select.Option value='Korean'>한국어</Select.Option> <Select.Option value='Japanese'>日本語</Select.Option> </Select> <Button style={{ marginRight: 10 }}>Switch to Overseas Version</Button> <Dropdown position="bottomRight" render={ <Dropdown.Menu> <Dropdown.Item>Detail</Dropdown.Item> <Dropdown.Item>Quit</Dropdown.Item> </Dropdown.Menu> } > <Avatar size="small" color='light-blue' style={{ margin: 4 }}>BD</Avatar> <span>Bytedancer</span> </Dropdown> </> } /> ); } renderVertical() { return ( <Nav bodyStyle={{ height: 320 }} items={this.items} onSelect={key => console.log(key)} footer={{ collapseButton: true, }} /> ); } render() { return ( <> {this.renderHorizontal()} {this.renderVertical()} </> ); } }

Expand and collapse arrow position

toggleIconPosition set 'left' or 'right', default right

Indentation limit

No indentation by default. If you need to indent the navigation items according to the level, please set limitIndent to false

When using Nav.Item to pass navigation items in React Jsx mode, please pass level props to Nav.Item manually.

Object method No need to care about level when passing in navigation items.

limitIndent only takes effect in the vertical direction.

Uncontrolled Properties

Including:

defaultSelectedKeys (default selected navigation item key array)
defaultOpenKeys (default expanded navigation item key array, valid only with mode = "vertical" and isCollapsed = false | defaultIsCollapsed = false)
defaultIsCollapsed (whether the sidebar is closed by default, valid only when mode = "vertical")

Controlled Properties

The Navigation component provides several controlled properties that, combined with a variety of callbacks, can easily control navigation.

The properties currently controlled are:

isCollapsed(whether the sidebar is closed, effective only when mode="vertical")
selectedKeys (currently selected navigation item key array)
openKeys (currently expanded array of navigation items, only mode="vertical" and isCollapsed=false valid)

The corresponding callback is:

onCollapseChange(isCollapsed: boolean) => void
onSelect ({ itemKey: string, selectedKeys: string[], domEvent: MouseEvent, isOpen: boolean }) => void
onOpenChange ({ itemKey: string, openKeys: string[], domEvent: MouseEvent, isOpen: boolean }) => void

import React, { useMemo } from 'react'; import { Nav } from '@douyinfe/semi-ui'; import { IconUser, IconStar, IconUserGroup, IconSetting } from '@douyinfe/semi-icons'; function NavApp (props = {}) { const [openKeys, setOpenKeys] = useState(['union-management', 'job']); const [selectedKeys, setSelectedKeys] = useState(['User Task Query']); const [isCollapsed, setIsCollapsed] = useState(true); const onSelect = data => { console.log('trigger onSelect: ', data); setSelectedKeys([...data.selectedKeys]); }; const onOpenChange = data => { console.log('trigger onOpenChange: ', data); setOpenKeys([...data.openKeys]); }; const onCollapseChange = isCollapsed => { setIsCollapsed(isCollapsed); }; const items = useMemo(() => [ { itemKey: 'user', text: 'User Management', icon: <IconUser /> }, { itemKey: 'union', text: 'Union Center', icon: <IconStar /> }, { itemKey: 'union-management', text: 'Union Management', icon: <IconUserGroup />, items: ['Announcement Settings', 'Union Query', 'Entry Information'] }, { text: 'Task Platform', icon: <IconSetting />, itemKey: 'job', items: ['Task Management', 'User Task Query'], }, ], []); return ( <Nav isCollapsed={isCollapsed} openKeys={openKeys} selectedKeys={selectedKeys} bodyStyle={{ height: 360 }} items={items} header={{ logo: <img src="https://sf6-cdn-tos.douyinstatic.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/webcast_logo.svg" />, text: 'Live Platform' }} footer={{ collapseButton: true }} onCollapseChange={onCollapseChange} onOpenChange={onOpenChange} onSelect={onSelect} /> ); }

API Reference

Nav

Properties	Type	Description	Default
bodyStyle	Custom style for navigation item list	object
className	Style name of outermost element	boolean
defaultIsCollapsed	Whether the default is put away, valid only when `mode = "vertical"`	boolean	false
defaultOpenKeys	Initially open sub navigation `itemKey` array, valid only `mode = "vertical"`and the sidebar is in an expanded state	string[]	[]
defaultSelectedKeys	Originally selected navigation item `itemKey` array	string[]	[]
expandIcon	Default Arrow Icon	ReactNode
footer	The bottom area configure objects or elements, see Nav.Footer	object\|ReactNode
getPopupContainer	Dropdown's getPopupContainer config of vertical collapsed Nav or horizontal Nav. >= v2.24	Function
header	Head area configuration objects or elements, see Nav.Header	object\|ReactNode
isCollapsed	A controlled attribute of whether it is in a put-away state, valid only when `mode = "vertical"`	boolean
items	Navigate the list of items, each item can continue with the items property. If it is a string array, each item is taken as text and itemKey	object\|string[]\|Item[]\|Sub[]
mode	Navigation type, currently supports horizontal and vertical, optional value: `vertical`\	`horizontal`	string
onClick	Trigger when clicking on any navigation item	(itemKey, event, isOpen) => void	() = > {}
onCollapseChange	The callback when the state changes.	(isCollapsed) => void	() = > {}
onOpenChange	Triggers when switching the hidden state of a sub navigation project	({itemKey, openKeys, event, isOpen}) => void	() = > {}
onSelect	Triggers the first time you select an optional navigation project, where the selected Items field version > = 0.17.0 is supported	(onSelectProps) => void	() = > {}
openKeys	Controlled open sub navigation `itemKey` array, expanded with `onOpenChange` callback control sub navigation items, valid only `mode = "vertical"`and the sidebar is in an unfolding state	string[]
renderWrapper	Custom navigation item outer component >=2.24.0	(data) => ReactNode
prefixCls	classsname prefix	string	`semi`
selectedKeys	Controlled navigation item `itemKey` array, with `onSelect` callback control navigation item selection	string[]
style	Custom styles for outermost elements	object
subNavCloseDelay	Delay of sub navigation floating layer closure. Effective when the limit is true or mode is "limit" in MS	number	100
subNavOpenDelay	The delay displayed by the sub navigation floating layer. Effective when the input is true or mode is "selected" in MS	number	0
tooltipHideDelay	The latency hidden by tooltip is valid when it is true in MS	number	100
tooltipShowDelay	The delay displayed by tooltip is valid when it is true in MS	number	0
limitIndent	To lift the indentation limit, you can use level to customize the indentation of navigation items. The horizontal mode can only be true >=1.27.0	boolean	true
toggleIconPosition	Parent navigation item arrow position with child navigation items >=1.27.0	'left' \| 'right'	'right'

Nav.Item

Properties	Description	Type	Default
disabled	Disabled state	boolean	false
icon	Navigation project icon name or component	ReactNode
indent	If the icon is empty, keep its space or not. Only effective for first level navigation	boolean	false
itemKey	Unique item identifier, no duplication allowed	string	""
level	The nesting level of the current item. When limitIndent is true, it is used to customize the indentation position	number
link	Navigation item href link, when imported, the navigation item will be wrapped with an a tag	string	-
linkOptions	Parameters transparently passed to the a tag	object	-
text	Navigation project copy or element	string \| ReactNode	""
onClick	Callback of click	function({ itemKey: string, domEvent: MouseEvent, isOpen: boolean })	() => {}
onMouseEnter	Callback of mouse enter event	function(e) => {}	() => {}
onMouseLeave	Callback of mouse leave event	function(e) => {}	() => {}

Nav.Sub

Properties	Description	Type	Default
disabled	Disabled state	boolean	false
dropdownStyle	Style of dropdown layer	CSSProperties
icon	Navigation project icon name or component	ReactNode
indent	If the icon is empty, keep its space or not. Only effective for first level navigation	boolean	false
isCollapsed	Whether it is a controlled attribute in the collapsed state, only `mode = "vertical"`	boolean	false
isOpen	Control open state	boolean	false
itemKey	Navigation project only key	string	""
level	The nesting level of the current item. When limitIndent is true, it is used to customize the indentation position	number
maxHeight	max height	number	999
text	Navigation project copy or component	string \| ReactNode	""
onMouseEnter	Callback of mouse enter event	function(e) => {}	() => {}
onMouseLeave	Callback of mouse leave event	function(e) => {}	() => {}

Nav.Header

Properties	Description	Type	Default
children	Sub element	ReactNode
className	Outermost style name	string
link	Navigation item href link, when imported, the navigation item will be wrapped with an a tag	string	-
linkOptions	Parameters transparently passed to the a tag	object	-
logo	Logo, can be a string or component	string \| ReactNode
style	Outermost style	object
text	Logo copy, which can be a string or component	string \| ReactNode

Nav.Footer

Properties	Description	Type	Default	Version
children	Sub element	ReactNode
className	Outermost style name	string
collapseButton	Whether to display the bottom "collapse sidebar" button, only work when mode="vertical" and the children parameter of the Footer component is empty	boolean\|ReactNode	false
collapseText	Title of the collapse button	(collapsed:boolean) => string\|ReactNode		0.35.0
style	Outermost style	object
onClick	Click callback	(event) => void

Accessibility

Keyboard and Focus
Each clickable item in the Navigation can be focused, use Tab and Shift + Tab to switch focus between each other, and each link can be activated by the Enter key
When an item can be opened popup
- The way to open the popup layer is hover : when the item is focused, the popup layer opens. Keyboard users can use the down arrow to move the focus to the bullet layer, and the Esc key can return the focus to the item
- The way to open the popup layer is click : when the item is focused, click the Enter key to open the popup layer. Keyboard users can use the down arrow to move the focus to the bullet layer, and the Esc key can return the focus to the item -Keyboard interaction does not fully support nested scenes

Content Guidelines

Navigation bar menu uses sentence case format
Keep it as simple as possible

Design Tokens

FAQ

Lost animation in navigation bar?
When using functional components, you should give items with useState or useMemo, because passing an array directly to items will trigger component rerendering.
Lost item when subNav is too height >=999px ? Please refer to this issue