NavBar | Tuff Docs

Usage

Loading demo...

Custom Left And Title Slots

Providing left replaces the built-in back icon. In that case a click emits click-left, not back.

<template>
  <TxNavBar @click-left="openMenu" @click-right="save">
    <template #left>
      <TxIcon name="i-carbon-menu" />
    </template>
    <template #title>
      <strong>Workspace</strong>
    </template>
    <template #right>
      Save
    </template>
  </TxNavBar>
</template>

<template>
  <TxNavBar title="Inbox" fixed :z-index="3200" />
</template>

Use safeAreaTop=false only when the parent layout already handles device safe-area padding.

Best Practices

Prefer @back for navigation history and reserve @click-left for custom left-slot actions.
Keep right-slot content short; the center title uses ellipsis but the side columns still need space.
Do not nest another interactive button inside left or right; the action zones are already buttons.
Keep safeAreaTop=true on mobile shells unless the surrounding layout already owns safe-area spacing.
Use disabled during route transitions or save operations to prevent duplicate navigation events.

API Reference

Props

Prop	Type	Default	Description
`title`	`string`	`''`	Text rendered in the center when no `title` slot is provided.
`fixed`	`boolean`	`false`	Uses sticky top positioning.
`safeAreaTop`	`boolean`	`true`	Renders a safe-area spacer using `env(safe-area-inset-top)`.
`showBack`	`boolean`	`false`	Shows the default left back icon when no `left` slot is provided.
`disabled`	`boolean`	`false`	Disables left/right buttons and suppresses events.
`zIndex`	`number`	`2000`	Value assigned to `--tx-nav-bar-z-index`.

Events

Event	Payload	Description
`back`	`void`	Emitted only by the default back button.
`click-left`	`void`	Emitted by the default back button or the custom left action.
`click-right`	`void`	Emitted by the right action when the `right` slot exists.

Slots

Slot	Props	Description
`left`	none	Replaces the default back icon and controls left-action content.
`title`	none	Replaces the centered title text.
`right`	none	Provides right-side action content.

Overview

The root is a header; left and right action zones are native button type="button" controls.
showBack=true renders the default back icon inside the left button when no left slot is provided.
Clicking the default back button emits both back and click-left.
Clicking a custom left slot emits only click-left.
Clicking a right slot emits click-right; an empty right zone is disabled and does not emit.
disabled=true adds is-disabled, disables both action buttons, and blocks all emits.
fixed=true applies sticky positioning at the top of the scroll container.
zIndex is exposed through --tx-nav-bar-z-index.

Technologies

Accessibility note: The left/right action zones are native buttons. Do not pass nested buttons in left or right; use text, icons, or spans inside the slot so the button semantics remain valid.
Event note: The default back affordance emits both back and click-left; custom left content emits only click-left. Use one listener path per interaction to avoid duplicate navigation.
Verified coverage: nav-bar.test.ts checks title/safe-area/z-index rendering, fixed and disabled classes, default back events, custom slot events, empty disabled zones, and disabled non-emission.
Component source: packages/tuffex/packages/components/src/nav-bar/src/TxNavBar.vue.
Types: packages/tuffex/packages/components/src/nav-bar/src/types.ts exports NavBarProps and NavBarEmits.
Export alias: packages/tuffex/packages/components/src/nav-bar/index.ts exports NavBar, TxNavBar, NavBarProps, NavBarEmits, and TxNavBarInstance.
Coverage: packages/tuffex/packages/components/src/nav-bar/__tests__/nav-bar.test.ts verifies structure, slots, safe-area behavior, and action events.

查看源码

packages/tuffex/packages/components/src/nav-bar/index.ts