Components

Navigation

Headless stack-navigation primitive — push/pop pages with iOS/Material-style slide transitions.

Overview

Navigation is a headless @vyui/core primitive for in-app stack navigation: a stack of pages where the top entry is visible, with push/pop slide transitions. State is driven by the useNavigationStack() composable; NavigationStack renders the active NavigationPage and animates between them.

This is a layer of @vyui/core — behavior only, no styles.

Anatomy

<NavigationStack>
  <NavigationPage />
  <!-- one NavigationPage per registered key -->
</NavigationStack>

Usage

<script setup lang="ts">
import {
  NavigationPage,
  NavigationStack,
  useNavigationStack,
} from '@vyui/core'

const stack = useNavigationStack({ key: 'home' })

function openDetail() {
  stack.push({ key: 'detail' })
}
</script>

<template>
  <NavigationStack
    :entries="stack.entries"
    :direction="stack.direction"
    transition="slide"
  >
    <NavigationPage page-key="home">
      <view class="p-4" bindtap="openDetail">
        <text>Home — tap to open detail</text>
      </view>
    </NavigationPage>
    <NavigationPage page-key="detail">
      <view class="p-4" bindtap="stack.pop">
        <text>Detail — tap to go back</text>
      </view>
    </NavigationPage>
  </NavigationStack>
</template>

Features and behavior

useNavigationStack() owns the stack; push, pop, replace, and reset update entries and direction.
entries drives which NavigationPage is visible — the top entry's key wins.
direction (forward / back / replace / reset) picks the enter/leave animation.
transition="slide" mirrors the iOS / Material push-pop slide; 'none' swaps instantly.

API

`NavigationStack`

Prop	Default	Type
`direction`	`"forward"`	`"replace" \| "reset" \| "forward" \| "back" \| undefined` Direction of the last navigation, used by `<NavigationPage>` to pick its enter/leave animation. `'forward'` = push, `'back'` = pop, `'replace'` / `'reset'` = no animation.
`entries`*	—	`NavigationStackEntry<any>[]` Reactive entries array — typically `stack.entries` from `useNavigationStack()`. The top entry's `key` decides which `<NavigationPage>` is visible.
`transition`	`"slide"`	`"slide" \| "none" \| undefined` Transition style. `'slide'` mirrors the iOS / Material push-pop slide; `'none'` is an instant swap. Slide animations are CSS-driven (see `NavigationPage.vue`) — apps can override per-page via slot content.

`NavigationPage`

Prop	Default	Type
`keepAlive`	`true`	`boolean \| undefined` When `false`, force-unmount even if this page matches the current stack key — useful for memory pressure or screen-specific reset.
`pageKey`*	—	`string` Stable identifier for this page. Must match the `key` of an entry in the stack's `entries` for the page to mount.

`useNavigationStack()`

Returns the stack controller: entries, direction, and the push / pop / replace / reset methods. Pass an initial entry to seed the stack.

Accessibility

Slide transitions are CSS-driven; respect reduced-motion preferences in your page content where appropriate.
Ensure each page sets a clear heading so context is announced after a push or pop.

Platform notes

Transitions are CSS-driven (see NavigationPage); apps can override per-page via slot content.

Tabs — flat switching between peers rather than a push/pop stack.
Sheet — present a page modally from the bottom edge.

Modal

Present a short blocking alert or confirmation dialog.

Number Field

Enter, increment, and constrain a numeric value.