Layout and state
Open the layout playground or the Layout tab in the top bar's Preferences drawer to switch navigation and workspace settings. Desktop modes are side (side), top (top), mixed (mixed), right (right), and split (split). Mixed mode puts first-level navigation at the top and displays only the active group's children in the sidebar. At widths of 768 px or less, navigation uses a drawer and preserves desktop preferences.
Live layout playground
Try a different navigation position, pin the header, or change content width. The preview uses Ray Admin's layout and settings components with its own menus and state.
View example source
<template>
<DemoFrame :dark="dark" :locale="locale">
<div
class="shell-demo"
:class="{ 'r-template--dark': dark }"
:lang="locale"
>
<AdminShell :layout="layout" :groupedSidebar="true" showTabs showFooter>
<template #header>
<div class="shell-bar">
<strong>Ray Admin</strong>
<NButton size="small" @click="dark = !dark">{{
dark ? copy.light : copy.dark
}}</NButton>
</div>
<ShellTopNavigation
v-if="['top', 'mixed', 'split'].includes(layout.mode)"
:items="menu"
:active="active"
:grouped="layout.mode !== 'top'"
:label="copy.navigation"
:select="(item) => navigate(item.fullPath)"
/>
</template>
<template #sidebar>
<NLayoutSider :width="132" bordered>
<nav
class="r-shell-menu"
:aria-label="copy.navigation"
@keydown="keyboard.onKeydown"
>
<NMenu
:options="menu"
:value="active"
:nodeProps="keyboard.nodeProps"
:dropdownProps="keyboard.dropdownProps"
@update:value="navigate"
/>
</nav>
</NLayoutSider>
</template>
<template #tabs>
<div class="shell-bar">
<ShellTab
v-for="item in pages"
:key="item.path"
:label="item.label"
:active="active === item.path"
:select="() => navigate(item.path)"
/>
</div>
</template>
<h2>{{ title }}</h2>
<LayoutSettings
:layout="layout"
:defaults="defaults"
:translate="translate"
:update="updateLayout"
/>
<template #footer>
<div class="shell-bar">{{ copy.footer }}</div>
</template>
</AdminShell>
</div>
</DemoFrame>
</template>
<script setup lang="ts">
import {
AdminShell,
LayoutSettings,
ShellTab,
ShellTopNavigation,
useMenuKeyboard,
} from '@ray-template/admin-shell'
import type { LayoutConfig } from '@ray-template/admin-shell'
import { NButton, NLayoutSider, NMenu } from 'naive-ui'
import { computed, onMounted, ref } from 'vue'
import { createMemoryHistory, createRouter } from 'vue-router'
import DemoFrame from './DemoFrame.vue'
const keyboard = useMenuKeyboard(false)
const props = withDefaults(defineProps<{ locale?: 'zh-CN' | 'en' }>(), {
locale: 'zh-CN',
})
const copy = computed(() =>
props.locale === 'en'
? {
dashboard: 'Dashboard',
reports: 'Reports',
navigation: 'Navigation',
light: 'Light theme',
dark: 'Dark theme',
footer: 'Layout preview',
settings: 'Layout',
side: 'Left',
top: 'Top',
mixed: 'Mixed',
right: 'Right',
split: 'Split',
contentWidth: 'Content width',
fluid: 'Fluid',
fixed: 'Fixed',
maxWidth: 'Maximum width',
padding: 'Padding',
fixedHeader: 'Fixed header',
fixedFooter: 'Fixed footer',
reset: 'Reset layout',
}
: {
dashboard: '工作台',
reports: '报表',
navigation: '导航',
light: '浅色主题',
dark: '深色主题',
footer: '布局预览',
settings: '布局',
side: '侧边导航',
top: '顶部导航',
mixed: '混合导航',
right: '右侧导航',
split: '通栏分组',
contentWidth: '内容宽度',
fluid: '流式铺满',
fixed: '定宽居中',
maxWidth: '最大宽度',
padding: '内容间距',
fixedHeader: '固定顶栏',
fixedFooter: '固定页脚',
reset: '恢复默认布局',
},
)
const translate = (key: string) =>
copy.value[(key === 'tab' ? 'settings' : key) as keyof typeof copy.value] ??
key
const defaults: LayoutConfig = {
mode: 'side',
contentWidth: 'fluid',
contentMaxWidth: 1200,
contentPadding: 16,
fixedHeader: true,
fixedFooter: true,
}
const layout = ref({ ...defaults })
const updateLayout = (patch: Partial<LayoutConfig>) => {
layout.value = { ...layout.value, ...patch }
}
const dark = ref(false)
const pages = computed(() => [
{ path: '/', label: copy.value.dashboard },
{ path: '/reports', label: copy.value.reports },
])
const router = createRouter({
history: createMemoryHistory(),
routes: pages.value.map(({ path }) => ({
path,
component: { render: () => null },
})),
})
const active = computed(() => router.currentRoute.value.path)
const title = computed(
() => pages.value.find(({ path }) => path === active.value)?.label,
)
const menu = computed(() =>
pages.value.map(({ path, label }) => ({
key: path,
label,
path,
fullPath: path,
name: path,
meta: {},
})),
)
const navigate = (path: string) => {
void router.push(path)
}
onMounted(() => navigate('/'))
</script>
<style scoped>
.shell-demo {
--html-height: 100dvh;
--html-width: 100vw;
--r-theme-primary-color: #3b63d9;
color: var(--r-text);
}
.shell-bar {
display: flex;
flex-wrap: wrap;
align-items: center;
gap: 12px;
padding: 10px 12px;
background: var(--r-surface);
border-block-end: 1px solid var(--r-line);
}
</style>Press Tab to focus menu items and Enter or Space to expand a group or open a page. Use Up and Down in the sidebar and Left and Right in the top menu. In submenus from the collapsed sidebar or top menu, use the arrow keys to select, Enter to open, and Esc to close.
Configure the workspace
import { useSettingActions } from '@/store'
const { updateSettingState } = useSettingActions()
updateSettingState('layoutConfig', {
mode: 'mixed',
contentWidth: 'fixed',
contentMaxWidth: 1200,
contentPadding: 24,
})Maximum width ranges from 640 to 2560 px, and padding ranges from 0 to 48 px. The header and footer can stay fixed or scroll with the content. The settings drawer defaults to Comfortable (24 px) and also offers Compact and Centered Reading presets. These presets adjust content width and padding while retaining navigation and fixed-bar settings. The preset area shows the active preset and actual spacing. Manual settings outside the presets show as custom spacing. Existing browser preferences carry forward. Restoring layout defaults applies the new default spacing and resets only layoutConfig. Older settings receive defaults for any missing fields.
Content maximization uses useMaximize. Close Preferences to see the result. At narrow widths, the exit button floats in the upper-right corner, leaving the content area free. Click the button or press Esc to restore the layout. A refresh resets maximization.
In Appearance, toggle breadcrumbs, tabs, and the footer together. Choose the page transition under Window and motion. Enter transitions take 240 ms and exit transitions take 190 ms, with small changes in position and scale. The outgoing page completes its transition before the incoming page enters. A reduced-motion system preference switches pages immediately. Restoring Appearance defaults preserves the current light or dark mode. The watermark panel offers Spaced, Compact, and Horizontal presets, a local preview, and shortcuts to fill in the app title or account nickname. You can adjust the style with the full-page watermark off. Presets preserve text and visibility. Reset buttons affect only the section they belong to.
Under Preferences → Appearance → Interface display, enable pill-shaped page tabs to change the tab shape. It defaults to off. The setting survives refresh and is included when exporting or importing preferences.
Page tabs and breadcrumbs
- Right-click a tab or open its actions menu to move it to the front or protect it. Moving a tab to the front places it at the left edge. Undoing this moves it to the start of the regular tab group. Protected tabs show a pin next to the title, hide the close button, and are protected from individual and bulk closing.
- Drag a tab, or focus it and use Shift + Left or Shift + Right to reorder it. While dragging, a preview follows the pointer and an insertion line marks the drop location. On touch screens, swipe the tab bar to scroll, or hold a tab and drag to reorder. Tabs promoted to the front and regular tabs reorder within their own groups. Order, promotion, and protection survive refresh within the current session.
- Breadcrumbs use the menu icons, including grouped SVG names and image VNodes on code-defined routes. The fallback is an outlined window icon. Narrow screens show the current path item and its icon.
Preferences → Appearance → Interface display has five independent switches, all on by default. Turning off tab protection or promotion pauses the effect and retains tab markers. Re-enabling the switch restores the effect. Turning off breadcrumb icons also hides the placeholder. You can turn the placeholder off on its own.
Menu icons
The expanded sidebar, mobile drawer, and top navigation use 20 px icons by default. The collapsed sidebar uses 22 px icons so entries remain identifiable from the glyph. Outline icons react to menu state and light or dark mode. In Preferences → Menu, change the icon size or collapsed icon size to apply it immediately. Compact and Comfortable presets adjust width, indentation, and icon size. You can also change collapse behavior, toggle the sidebar, scroll it to the top, or refresh the menu. Layouts without a desktop sidebar disable the sidebar quick actions and retain the configured sizes.
Replace layout regions
RLayout exposes header, sidebar, tabs, footer, and default slots. Layout mode and visibility settings still apply. For example, the top navigation mode omits the sidebar region. Supply route caching and request cancellation as needed when replacing the default content.
Where state lives
| State | Entry point | After refresh |
|---|---|---|
| Loading, mobile drawer, content maximization, and reload | useRuntimeGetters / useRuntimeActions | New runtime state. |
| Layout, theme, language, and other preferences | useSettingGetters / useSettingActions | Restores cached preferences and fills missing defaults. |
| Lock screen | Lock Screen Store | Retains the legacy boolean format and syncs across tabs. |
The General panel uses updateLocale to keep the UI, component library, and date locale in sync. It also exposes refresh, scroll to top, and cache management. You can adjust the cache limit, and the UI explains the policy. Clearing the cache releases inactive page instances and keeps the current one. Later visits recreate instances according to the cache settings. Refreshing the current page remounts it, so unsaved inputs can be lost. Restoring General defaults resets the dynamic title and cache settings while retaining language, recent pages, and favorites.
Place shared state by responsibility in apps/admin/src/store/modules and expose it through store hooks. Choose persisted fields with pick or omit. Check legacy keys and serialized formats before changing them.
Layout and slots · State and persistence
Setting Store · Runtime Store · Layout hooks
Recent pages and favorites
Press Ctrl or Command + K on desktop to open search. Search by page name and click a star to add a favorite. With an empty query, it shows favorites and recent pages. Use the arrow keys, Enter, or Tab to operate it. Entries are scoped to the session user ID and restored on refresh. Clearing history keeps favorites. You can also clear the current account's recent pages after confirmation in Preferences → General. The cache stores only menu paths. Display resolves them against the current menus, permissions, and translations. On mobile, use the top bar's search button. The navigation drawer has a Close button. A width change preserves the desktop sidebar's collapse preference.
When content should fill the workspace, reuse --layout-content-height, RTablePro autoHeight, and --r-table-height, or Naive UI's NCard contentScrollable or NScrollbar. Give the parent a definite height. Flex and grid children can use min-block-size: 0 before hosting internal scrolling. The User Management page scrolls the left and right panels independently on desktop. At narrow widths, the page scrolls vertically, the organization tree has a height limit, and the table retains its own horizontal scrolling.