React Bootstrap logoReact Bootstrap

Navbar

基础导航

基于 Bootstrap 5 的导航栏组件，Navbar 系列（Navbar、NavbarBrand、NavbarCollapse、NavbarToggle、NavbarText、NavbarOffcanvas）用于构建响应式顶部导航，支持折叠断点、受控/非受控展开状态、选择后自动收起、配色方案、固定与粘性定位、滚动导航与抽屉式导航，可与 Nav、Dropdown、表单等组件自由组合

Component Demo

Basic usage and examples of the Navbar component

支持的内容

导航栏由 Navbar 容器加 Brand、Nav、表单与 Text 等子内容组成；Nav 渲染 `ul.nav`，配合 `me-auto` 等 Flex 工具类即可排出常见布局

品牌 Brand

NavbarBrand 渲染 `navbar-brand` 类；设置 href 后渲染为链接，也可以放入 Logo 图片与文案

导航链接

导航栏内的 Nav 自动追加 `navbar-nav` 类，NavLink 自动携带 `nav-link` 类，激活链接渲染 `active` 类并设置 `aria-current="page"`

表单与下拉菜单

`d-flex` 表单与 Dropdown 等组件可以直接放入导航栏，配合容器类即可控制对齐方式

文本

NavbarText 渲染 `navbar-text` 类，为纯文本提供与导航栏一致的内边距与颜色

配色方案

data-bs-theme 控制导航栏内容的配色，bg 提供背景色；variant 属性渲染的 `navbar-light`/`navbar-dark` 在 Bootstrap 5.3 中已弃用，建议统一使用 data-bs-theme

容器

在 Navbar 内包裹 `container`、`container-fluid` 或 `container-{breakpoint}` 即可按需求限制内容宽度

定位方式

fixed-top 固定在区块顶部，内容通过预留的顶部间距避免被遮挡；实际页面中为 body 添加 padding-top 即可。
fixed-bottom 固定在区块底部，内容通过预留的底部间距避免被遮挡；实际页面中为 body 添加 padding-bottom 即可。

滚动内容 1，sticky-top 导航栏会吸附在滚动容器顶部。

滚动内容 2，sticky-top 导航栏会吸附在滚动容器顶部。

滚动内容 3，sticky-top 导航栏会吸附在滚动容器顶部。

滚动内容 4，sticky-top 导航栏会吸附在滚动容器顶部。

滚动内容 5，sticky-top 导航栏会吸附在滚动容器顶部。

滚动内容 6，sticky-top 导航栏会吸附在滚动容器顶部。

滚动内容 7，sticky-top 导航栏会吸附在滚动容器顶部。

滚动内容 8，sticky-top 导航栏会吸附在滚动容器顶部。

滚动内容 9，sticky-top 导航栏会吸附在滚动容器顶部。

滚动内容 10，sticky-top 导航栏会吸附在滚动容器顶部。

fixed 渲染 `fixed-top`/`fixed-bottom`（此处通过 transform 容器演示固定效果，并预留了与导航栏 等高的间距避免遮挡内容），sticky 渲染 `sticky-top`/`sticky-bottom`，在滚动容器中可观察真实的吸附行为

滚动导航

给 Nav 添加 `navbar-nav-scroll` 类并设置 `--bs-scroll-height` 变量后，链接在 expand 断点以下会改为纵向滚动；缩小窗口即可观察滚动效果

响应式行为

缩小窗口宽度即可看到折叠按钮：NavbarToggle 与 NavbarCollapse 通过 aria-controls/id 互相关联，点击折叠按钮自动维护展开状态；设置 collapseOnSelect 后移动端点击 NavLink 会自动收起导航栏

受控与外部内容

传入 expanded 与 onToggle 后导航栏变为受控组件，展开状态完全由外部 state 决定， 因此可以在导航栏之外的任意位置控制其展开与收起

Offcanvas 抽屉导航

缩小窗口后点击折叠按钮，NavbarOffcanvas 会以抽屉形式从右侧滑出（遮罩点击与 Esc 均可关闭，打开期间锁定页面滚动）；头部关闭按钮通过 useNavbar 取得 onToggle 收起导航栏。桌面端由 `navbar-expand-lg` 样式自动切换为内联布局；表单使用 `mt-3 mt-lg-0`、Nav 使用 `pe-3` 保持两种布局下与导航的间距和对齐

API Documentation

Complete API reference for the Navbar component

Props

Navbar

属性名类型默认值描述
asElementType'nav'根元素标签，默认渲染 `nav.navbar`
expandboolean | NavbarExpandtrue折叠断点，控制导航栏在哪个屏幕尺寸以下折叠：`true` 渲染 `navbar-expand`（始终展开），`false` 不渲染展开类（始终可折叠），断点渲染 `navbar-expand-{breakpoint}`
expandedboolean-受控展开状态，配合 onToggle 实现受控导航栏；未设置时由组件内部维护展开状态（初始为收起）
onToggle(expanded: boolean) => void-展开状态变化回调，在 NavbarToggle 点击或 collapseOnSelect 收起时以新的 expanded 值触发
onSelect(eventKey: EventKey, event: SyntheticEvent) => void-选择回调，在导航栏内 Nav 后代的 NavLink 被选择时触发，用于执行导航后的附加操作
collapseOnSelectbooleanfalse移动端在 Nav 后代被选择后自动收起导航栏（等价于调用 onToggle(false)），适合点击链接后关闭菜单的场景
bgstring-背景工具类，渲染 `bg-*` 类，常用 `dark`、`light`、`primary`、`body-tertiary`，也支持任意自定义背景类
data-bs-themestring-Bootstrap 5.3 配色方案（如 `dark`），控制导航栏内链接、表单等内容的颜色，推荐代替已弃用的 variant
variantNavbarVariant-视觉变体，渲染 `navbar-light`/`navbar-dark` 类；Bootstrap 5.3 已弃用，推荐改用 data-bs-theme
fixedNavbarFixed-固定定位，渲染 `fixed-top`/`fixed-bottom` 类，导航栏随页面滚动保持在顶部或底部
stickyNavbarFixed-粘性定位，渲染 `sticky-top`/`sticky-bottom` 类，滚动经过后才固定在顶部或底部
rolestring'navigation'无障碍角色；as 渲染为 `nav` 时使用浏览器默认语义，渲染为其他元素时默认设置该角色

NavbarBrand

属性名类型默认值描述
asElementTypehref ? a : span渲染的元素标签，默认设置了 href 渲染 `a`，否则渲染 `span`
hrefstring-品牌链接地址，设置后默认渲染为 `a.navbar-brand`

NavbarCollapse

属性名类型默认值描述
childrenReactNode-响应式折叠区内容，渲染 `div.collapse.navbar-collapse`，展开时由 Navbar 的 expanded 状态添加 `show` 类；桌面端由 `navbar-expand-*` 样式保持可见，移动端随 NavbarToggle 显示或隐藏

NavbarToggle

属性名类型默认值描述
asElementType'button'渲染的元素标签，默认渲染 `button.navbar-toggler`（自动设置 type="button"）
labelstring'Toggle navigation'折叠按钮的无障碍标签，写入 aria-label
childrenReactNode-自定义按钮内容，未设置时渲染默认的 `span.navbar-toggler-icon` 图标

NavbarText

属性名类型默认值描述
asElementType'span'渲染的元素标签，默认渲染 `span.navbar-text`

NavbarOffcanvas

属性名类型默认值描述
placementNavbarOffcanvasPlacement'start'抽屉方向，渲染 `offcanvas-start`/`offcanvas-end`/`offcanvas-top`/`offcanvas-bottom`
backdropboolean | 'static'true遮罩配置：`true` 渲染可点击关闭的遮罩，`"static"` 渲染点击不关闭的遮罩，`false` 不渲染遮罩
keyboardbooleantrue是否支持按下 Esc 关闭抽屉
scrollbooleanfalse打开期间是否允许页面滚动，默认锁定页面滚动
durationnumber300滑入/滑出过渡毫秒数，写入 `--bs-offcanvas-transition`；用户偏好减少动态效果时忽略
onHide() => void-遮罩点击或 Esc 触发关闭时的回调，先收起导航栏再触发
onEnter…() => void-过渡各阶段回调：onEnter/onEntering/onEntered/onExit/onExiting/onExited

Common Props

属性名类型默认值描述
childrenReactNode-组件内容
classNamestring-自定义类名
...restHTMLAttributes-透传原生元素属性（如 `id`、`style`、`aria-*` 等）

Type Definitions

NavbarExpand

导航栏折叠断点类型

export type NavbarExpand = 'lg' | 'md' | 'sm' | 'xl' | 'xxl';

NavbarFixed

导航栏定位方式类型

export type NavbarFixed = 'bottom' | 'top';

NavbarVariant

导航栏视觉变体类型

export type NavbarVariant = 'dark' | 'light';

NavbarOffcanvasPlacement

抽屉导航方向类型

export type NavbarOffcanvasPlacement = 'bottom' | 'end' | 'start' | 'top';

NavbarProps

导航栏组件属性接口

export interface NavbarProps extends Omit<HTMLAttributes<HTMLElement>, 'onSelect' | 'onToggle'> {
  'data-bs-theme'?: string;
  as?: ElementType;
  bg?: string;
  children?: ReactNode;
  className?: string;
  collapseOnSelect?: boolean;
  expand?: boolean | NavbarExpand;
  expanded?: boolean;
  fixed?: NavbarFixed;
  onSelect?: (eventKey: EventKey, event: SyntheticEvent) => void;
  onToggle?: (expanded: boolean) => void;
  role?: string;
  sticky?: NavbarFixed;
  variant?: NavbarVariant;
}

NavbarContextValue

导航栏上下文，供各子组件与 Nav 消费

export interface NavbarContextValue {
  expand?: boolean | NavbarExpand;
  expanded: boolean;
  onSelect: (eventKey: EventKey, event: SyntheticEvent) => void;
  onToggle: () => void;
}

NavbarBrandProps

导航栏品牌组件属性接口

export interface NavbarBrandProps extends HTMLAttributes<HTMLElement> {
  as?: ElementType;
  children?: ReactNode;
  className?: string;
  href?: string;
}

NavbarCollapseProps

导航栏折叠区组件属性接口

export interface NavbarCollapseProps extends HTMLAttributes<HTMLDivElement> {
  children?: ReactNode;
  className?: string;
}

NavbarOffcanvasProps

抽屉导航组件属性接口

export interface NavbarOffcanvasProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onHide'> {
  backdrop?: boolean | 'static';
  children?: ReactNode;
  className?: string;
  duration?: number;
  keyboard?: boolean;
  onEnter?: () => void;
  onEntered?: () => void;
  onEntering?: () => void;
  onExit?: () => void;
  onExited?: () => void;
  onExiting?: () => void;
  onHide?: () => void;
  placement?: NavbarOffcanvasPlacement;
  scroll?: boolean;
}

NavbarTextProps

导航栏文本组件属性接口

export interface NavbarTextProps extends HTMLAttributes<HTMLElement> {
  as?: ElementType;
  children?: ReactNode;
  className?: string;
}

NavbarToggleProps

折叠按钮组件属性接口

export interface NavbarToggleProps extends HTMLAttributes<HTMLElement> {
  as?: ElementType;
  children?: ReactNode;
  className?: string;
  label?: string;
}