Navbar

17:06

Description

A custom top navigation bar: back icon and back text, a centered title, left / default / right slots, gradient or solid backgrounds, plus fixed and immersive modes. In fixed mode it reserves space for the status bar and pushes the content below it (immersive removes the placeholder); the default height is 44px on App / H5, and 44px on iOS / 48px on Android for WeChat Mini Program. Use uni-app's native navigation bar unless you need this level of customization.

Compatibility

Platform	Support
App	✅ Supported (default height 44px)
H5	✅ Supported (default height 44px)
WeChat Mini Program	✅ Supported (default height 44px on iOS / 48px on Android)

Examples

Basic Usage

Fixed at the top by default, with a back icon and centered title; supports a back text.

View source

<template>
    <ux-navbar :title="title" :is-fixed="false" />
    <ux-navbar :title="title" back-text="返回" :is-fixed="false" />
</template>

<script setup lang="uts">
const title = ref<string>('导航标题');
</script>

Title Style

Style the title via title-bold, title-size and title-color; title-width limits width with single-line ellipsis.

View source

<template>
    <ux-navbar :title="defaultTitle" :is-fixed="false" />
    <ux-navbar :title="boldTitle" title-bold title-size="18" :is-fixed="false" />
    <ux-navbar :title="primaryTitle" title-color="#2979ff" :is-fixed="false" />
    <!-- 超长标题：title-width 限制最大宽度，超出单行省略 -->
    <ux-navbar :title="longTitle" title-width="120" :is-fixed="false" />
</template>

<script setup lang="uts">
const defaultTitle = ref<string>('导航标题');
const boldTitle = ref<string>('加粗大标题');
const primaryTitle = ref<string>('主题蓝标题');
const longTitle = ref<string>('这是一个很长的标题，超出部分将显示省略号');
</script>

Back Bar

is-back controls back visibility; back-text, back-icon-name/size/color customize the back bar.

View source

<template>
    <ux-navbar :title="title" :is-fixed="false" />
    <ux-navbar :title="noBackTitle" :is-back="false" :is-fixed="false" />
    <ux-navbar :title="title" back-text="上一页" back-icon-name="arrow-left" :is-fixed="false" />
    <ux-navbar :title="title" back-icon-color="#2979ff" back-icon-size="18" :is-fixed="false" />
</template>

<script setup lang="uts">
const title = ref<string>('返回栏');
const noBackTitle = ref<string>('隐藏返回');
</script>

Background Color

background supports linear gradient and solid color.

View source

<template>
    <ux-navbar :title="title" :background="gradient" back-icon-color="#ffffff" title-color="#ffffff" :is-fixed="false" />
    <ux-navbar :title="title" :background="{ background: '#39CCCC' }" back-icon-color="#ffffff" title-color="#ffffff" :is-fixed="false" />
    <ux-navbar :title="title" :background="{ background: '#B471CC' }" back-icon-color="#ffffff" title-color="#ffffff" :is-fixed="false" />
</template>

<script setup lang="uts">
const title = ref<string>('背景色');
const gradient = ref<UTSJSONObject>({
    'background-image': 'linear-gradient(90deg, rgb(28, 187, 180), rgb(141, 198, 63))'
});
</script>

Custom Slots

left / default / right slots to customize the left, center and right areas.

View source

<template>
    <ux-navbar :background="gradient" back-icon-color="#ffffff" :is-fixed="false">
        <template #left>
            <text style="color:#ffffff;font-size:11px;">左侧</text>
        </template>
        <!-- 默认插槽：居中内容区 -->
        <text style="flex:1;color:#ffffff;font-size:14px;text-align:center;">轻舟已过万重山</text>
        <template #right>
            <ux-icon name="chat" size="18" color="#ffffff" />
            <ux-icon name="calendar-fill" size="18" color="#ffffff" />
        </template>
    </ux-navbar>
</template>

<script setup lang="uts">
const gradient = ref<UTSJSONObject>({
    'background-image': 'linear-gradient(90deg, rgb(28, 187, 180), rgb(141, 198, 63))'
});
</script>

Custom Back Event

custom-back overrides the default back behavior for interception or custom logic.

View source

<template>
    <ux-navbar title="自定义返回" :custom-back="customBack" :is-fixed="false" />
    <text>点击返回按钮不会退出页面，而是触发自定义事件</text>
</template>

<script setup lang="uts">
const customBack = () => {
    uni.showToast({ title: '拦截了返回事件', icon: 'none' });
};
</script>

Border & Height

border-bottom controls the bottom border; height customizes the navbar height.

View source

<template>
    <ux-navbar :title="noBorder" :border-bottom="false" :is-fixed="false" />
    <ux-navbar :title="customHeight" height="56" :is-fixed="false" />
</template>

<script setup lang="uts">
const noBorder = ref<string>('无下边框');
const customHeight = ref<string>('自定义高度');
</script>

Fixed & Immersive

is-fixed pins to top, immersive removes the fixed placeholder, z-index controls stacking.

View source

<template>
    <!-- is-fixed=true 固定在页面顶部（默认），下方内容随页面滚动 -->
    <ux-navbar title="固定导航栏" back-text="返回"
        :background="{ 'background-image': 'linear-gradient(90deg, rgb(28,187,180), rgb(141,198,63))' }"
        back-icon-color="#ffffff" title-color="#ffffff" />
</template>

<script setup lang="uts">
const title = ref<string>('固定导航栏');
</script>

API

Props

Property	Description	Type	Default	Version
height	Navbar height in px (px only); the status bar height is added internally	string | number	''	-
backIconColor	Color of the back arrow	string	''	-
backIconName	Icon for the left back button	string	'nav-back'	-
backIconSize	Size of the left back icon, in px	string | number	'18'	-
backText	Text hint shown next to the back icon	string	''	-
backTextColor	Color of the back text	string	''	-
backTextStyle	Style of the back text	UTSJSONObject	-	-
title	Navbar title	string	''	-
titleWidth	Max width of the title, in px	string | number	'180'	-
titleColor	Title color	string	''	-
titleBold	Whether the title is bold	boolean	false	-
titleSize	Title font size	string | number	16	-
isBack	Whether to show the left back icon and its text	boolean | string	true	-
background	Navbar background settings	UTSJSONObject	-	-
isFixed	Whether the navbar is fixed at the top	boolean	true	-
immersive	Whether immersive; lets the navbar collapse after fixed positioning (only effective with fixed)	boolean	false	-
borderBottom	Whether to show the navbar bottom border	boolean	true	-
zIndex	z-index value when fixed at the top	string | number	''	-
customBack	Custom back-handling function	() => void	-	-
customClass	Custom class name	string	''	-
customStyle	Custom style	string | UTSJSONObject	-	-

Events

ux-navbar has no events.

Slots

Slot	Description	Version
left	Custom left content area (after the back area, before the title)	-
default	Custom center content area (after the title, before the right slot; for centered content beyond the title)	-
right	Custom right content area (at the far right of the navbar)	-

Notes

• The default height differs by platform: 44px on App / H5, and 44px on iOS / 48px on Android for WeChat Mini Program; height excludes the status bar height, which the component adds as a placeholder internally.
• When is-fixed=true it adds a status-bar placeholder to push the content below the system status bar; use immersive to remove the placeholder (effective only when fixed).
• The back text must sit inside <text>: on App color only applies to text, and bare text also loses parent color inheritance.
• Title single-line ellipsis: App uses the native <text max-lines="1"> ellipsis, while H5 / WeChat Mini Program use -webkit-line-clamp.
• Slot content does not inherit styles on App — set colors on the inner text and icons explicitly.
• Once custom-back is provided, the back button no longer calls uni.navigateBack(); the callback takes over.