Skip to content

OrigamBottomNav ​

<OrigamBottomNav> is the fixed-to-viewport navigation bar for mobile / compact layouts — a <nav> pinned to the bottom of the screen showing a row of destination buttons (each one an <OrigamBtn>). It registers itself as a bottom-positioned layout item with the surrounding <OrigamLayout>, so <OrigamMain> and other layout regions offset correctly, and it slides in/out via a transition when toggled.

Basic usage ​

vue
<template>
    <OrigamLayout>
        <OrigamMain>…</OrigamMain>

        <OrigamBottomNav :items="items" />
    </OrigamLayout>
</template>

<script setup lang="ts">
import { MDI_ICONS } from '@origam/enums'

const items = [
    { text: 'Home',    prependIcon: MDI_ICONS.HOME,    value: 'home'    },
    { text: 'Search',  prependIcon: MDI_ICONS.MAGNIFY, value: 'search'  },
    { text: 'Profile', prependIcon: MDI_ICONS.ACCOUNT, value: 'profile' },
]
</script>

Each entry of items is spread as props onto an internally-rendered <origam-btn> (v-bind="item"), so any IBtnProps field — text, prependIcon/appendIcon, icon, value, disabled, to/href… — works out of the box.

Mode ​

Three layouts for the button row, via the mode prop (TNavMode, backed by the MODE enum):

ValueDescription
vertical (default)Icon above label, centered in a 3-row grid (prepend / content / append).
horizontalIcon and label side by side; each button's inline loader area is shown as flex.
shiftSame grid as vertical, plus the label of every non-selected item fades out and slides down by 0.5rem — only the active item shows its text.
vue
<template>
    <OrigamBottomNav :items="items" mode="shift" />
</template>

Position ​

When the bar is given a custom width (so it no longer spans edge to edge), position (TBottomNavPosition, backed by BOTTOM_NAV_POSITION) chooses where it sits horizontally:

ValueDescription
start (default)Pinned to the inline-start edge (left: 0).
centerCentered (left: 0; right: 0; margin-inline: auto).
endPinned to the inline-end edge (right: 0).
vue
<template>
    <OrigamBottomNav :items="items" width="360px" position="center" />
</template>

Grow ​

grow stretches every child button to share the available width evenly (flex-grow: 1 on each .origam-btn), instead of each button sizing to its own content (bounded by min-width: 80px / max-width: 168px).

vue
<template>
    <OrigamBottomNav :items="items" grow />
</template>

Color ​

color / bgColor are forwarded as defaults to every child <origam-btn> (via OrigamDefaultsProvider) — items that set their own color/bgColor still win. hover and active are forwarded the same way, so a state-aware palette configured on the bar cascades to every button:

vue
<template>
    <OrigamBottomNav
        :items="items"
        color="primary"
        bg-color="primary"
        :active="{ bgColor: 'success' }"
    />
</template>

The bar's own surface deliberately does not react to hover/active — isHover / isActive are hard-wired to false when resolving the bar's own resting color, since the container itself shouldn't darken on hover; only its buttons should.

Visibility ​

modelValue (default true) controls whether the bar is mounted and slid into view. Toggling it off transitions the bar out via the transition prop (see below) and unmounts it.

vue
<template>
    <OrigamBottomNav :model-value="isVisible" :items="items" />
</template>

Note: modelValue is shared with the item-group mechanics below — the same prop simultaneously drives "is the bar shown" (useActive) and, through useGroup, the selected item value(s) for the button group. Passing a non-boolean modelValue (e.g. a selected item's value) still resolves truthy for visibility purposes.

Group selection (multiple / mandatory / disabled) ​

The bar's child buttons form a single-select (or multi-select) item group out of the box — clicking one applies selectedClass ('origam-bottom-nav__btn--selected' by default) to it.

PropTypeDefaultDescription
multipleboolean—Allow more than one selected item at a time.
mandatoryboolean—Prevent deselecting the last remaining active item.
maxnumber—Caps how many items can be selected when multiple is set.
disabledboolean—Disables the whole group (all child buttons).
selectedClassstring'origam-bottom-nav__btn--selected'Class applied to the currently selected button(s).

Layout placement ​

<OrigamBottomNav> is layout-aware, using the standard name / order / location / absolute quadruple from ILayoutItemProps:

  • name (default 'bottom-navigation') — unique id used by the layout machinery.
  • order — relative order against sibling layout items.
  • location (default 'bottom') — which edge of the <OrigamLayout> the bar docks against: 'top' · 'bottom' · 'left' · 'right'. It drives the anchor, the direction the bar slides in from, the calc() height/width, and how much room sibling regions give up.
  • absolute — opt out of pushing/pulling sibling regions; the bar then floats over the main slot instead.
vue
<template>
    <OrigamLayout>
        <OrigamMain>…</OrigamMain>
        <OrigamBottomNav name="tabs" order="0" :items="items" />
    </OrigamLayout>
</template>

location and position are two different axes

location is the edge the bar docks against inside the layout (top / bottom / left / right). position is the horizontal alignment of the bar within that edge when it does not span the full width (start / center / end). They only interact when location is itself horizontal ('left' / 'right'), where the origam-bottom-nav--position-* rule and the layout anchor compete for the same axis — the family's supported rendering stays location="bottom".

The default transition (OrigamTranslateBottom) always slides in from the bottom. Pair a non-default location with a matching transition, or :transition="false".

Transition ​

transition accepts boolean | string | TTransitionProps and defaults to a slide-up-from-the-bottom transition (OrigamTranslateBottom, passed as a component descriptor rather than a bare name so its <style> is guaranteed to be registered). Pass false to disable the enter/leave animation, or another transition component/name to replace it.

Slots ​

SlotSlot propsDescription
default—Overrides the entire items rendering; falls back to iterating items.
item.{index}{ props: item }Overrides a single item by index.
item{ props: item, index }Overrides the rendering of every item (falls back to <origam-btn v-bind="item" />).
vue
<template>
    <OrigamBottomNav :items="items">
        <template #item="{ props: itemProps, index }">
            <OrigamBtn v-bind="itemProps" :data-cy="`nav-item-${index}`" />
        </template>
    </OrigamBottomNav>
</template>

Emits ​

EventPayloadDescription
update:modelValueanyVisibility / group-selection changes (see the note above).
update:hoverbooleanPropagated from IHoverProps state.

Note: IBottomNavProps still accepts active / activeClass (IActiveProps) as a default forwarded to child <OrigamBtn> items, but the nav itself does not emit update:active — its own "active" (shown/hidden) state is sourced from modelValue, not from active. See the interface comment on IBottomNavEmits (bottom-nav.interface.ts) for the full reasoning.

Props (interface) ​

ts
interface IBottomNavProps extends ITagProps, ICommonsComponentProps,
    IColorProps, IBgColorProps, IPaddingProps, IBorderProps,
    IElevationProps, IMarginProps, IDimensionProps, IDensityProps,
    IRoundedProps, ILayoutItemProps, IGroupProps, IHoverProps,
    IActiveProps, ITransitionComponentProps {
    grow?: boolean
    mode?: TNavMode
    items?: Array<IBtnProps>
    position?: TBottomNavPosition
}
PropTypeDefaultDescription
tagstring'nav'Root element/component.
itemsArray<IBtnProps>[]Destinations rendered as <origam-btn> instances.
modeTNavMode'vertical'Layout of icon + label — see Mode.
positionTBottomNavPosition'start'Horizontal placement when the bar has a custom width — see Position.
growboolean—Stretch every child button to share the width evenly.
color / bgColorTColor—Forwarded as defaults to every child button.
densityTDensity—Inherits from IDensityProps; 'compact' reduces the bar height by 8px.
rounded, border(+ color/style), elevation——Standard shape surface — see IRoundedProps / IBorderProps / IElevationProps.
padding*, margin*——Standard spacing surface — see IPaddingProps / IMarginProps.
height, width, min/maxHeight, min/maxWidth——Standard dimension surface — see IDimensionProps. When height is set, the actual applied height is height minus 8px in compact density.
name, order, absolute—name: 'bottom-navigation'Layout placement — see Layout placement.
locationTDirectionBoth'bottom'Edge of the <OrigamLayout> the bar docks against (top · bottom · left · right). Distinct from position — see Layout placement.
modelValue, disabled, multiple, mandatory, max, selectedClass—modelValue: true, selectedClass: 'origam-bottom-nav__btn--selected'Visibility + group selection — see Visibility / Group selection.
hover, active, activeClassboolean | IHoverState / boolean | IActiveState—State-aware overrides forwarded to child buttons — see Color.
transitionboolean | string | TTransitionProps{ component: OrigamTranslateBottom }Enter/leave animation — see Transition.

Anatomy ​

html
<nav class="origam-bottom-nav origam-bottom-nav--{mode} origam-bottom-nav--position-{position}">
    <div class="origam-bottom-nav__content">
        <!-- one <origam-btn class="origam-bottom-nav__btn"> per item -->
    </div>
</nav>

Design tokens consumed ​

<OrigamBottomNav> reads its variables from packages/ds/src/assets/css/tokens/light.css and dark.css (SCSS twins under packages/ds/src/assets/scss/tokens/), under the --origam-bottom-nav---* prefix — matching the component's own name, per the DS naming grammar. The legacy --origam-bottom-bar---* prefix still works as a deprecated alias; see the note below the table.

CSS variableToken reference
--origam-bottom-nav---background{color.neutral.200}
--origam-bottom-nav---color{color.text.primary}
--origam-bottom-nav---height{space.12} (48px)
--origam-bottom-nav---box-shadow{shadow.none}
--origam-bottom-nav--elevated---box-shadowshadow projected upward (negative offset-Y), so it isn't clipped by the viewport edge
--origam-bottom-nav--active---box-shadowsame upward shadow, applied while the bar is active
--origam-bottom-nav---border-radius{radius.none} at rest. The token layer also generates --origam-bottom-nav__rounded---border-radius: {radius.sm} (4px) for the rounded state, but nothing in OrigamBottomNav.vue's SCSS reads that variable — the &--rounded rule hardcodes var(--origam-radius---2xl, 24px) directly (OrigamBottomNav.vue:400), so the applied radius is 24px, not {radius.sm}.
--origam-bottom-nav---density / -comfortable-density / -compact-densitydensity-driven padding/height offset
--origam-bottom-nav__content---justify-content / -align-items / -flex-wraplayout of the items row

--origam-bottom-bar---* is deprecated

Until now every one of this component's variables carried the prefix --origam-bottom-bar---*, while the component itself is origam-bottom-nav — so a theme author who followed the DS naming grammar (--origam-{component}---{property}) and wrote --origam-bottom-nav---background got nothing at all, with no warning.

The tokens now carry the correct --origam-bottom-nav---* prefix. The old names keep working for one version: each new token is declared as var(--origam-bottom-bar---x, <value>), so anything you already set under the old prefix still wins. Nothing to change today; migrate at your leisure, the alias is removed in the next major.

Rename mechanically — --origam-bottom-bar → --origam-bottom-nav, the property part is unchanged.

| --origam-bottom-nav__content---transform | Generic content-level transform override hook (OrigamBottomNav.vue:359). Naming matches the generated token exactly — no mismatch. Not what powers shift mode, though: &--shift's label fade/slide (OrigamBottomNav.vue:501-513) sets a literal transform: translateY(0.5rem) directly on the more specific .origam-btn__content selector, so overriding this variable has no visible effect while shift is active — see bottom-nav-shift.spec.ts for the non-regression coverage of that mode. | | --origam-bottom-nav---padding-*, --origam-bottom-nav---margin-* | spacing (also driven by the padding / margin props) |

The full list lives in packages/ds/src/assets/css/tokens/light.css and dark.css — grep for --origam-bottom-nav.

Accessibility ​

  • Renders a <nav aria-label="Bottom navigation"> by default — the label goes through the DS's useLocale() translation layer (t('origam.bottom_nav.aria_label', 'Bottom navigation'), OrigamBottomNav.vue:10/:112), same pattern as <OrigamBreadcrumb>'s aria-label. The bottom_nav key is declared in both en.json and fr.json.
  • Full keyboard support comes from the underlying <origam-btn> instances (native <button>/<a> semantics).

Theming notes ​

  • The component is theme-aware out of the box. Switching <html data-theme="…"> re-resolves every variable instantly.
  • A sub-tree can opt into a different theme via <OrigamThemeProvider>.
  • OrigamBtn — the component rendered for each item.
  • OrigamLayout / OrigamMain — the layout region system the bar registers into.
  • OrigamSystemBar / OrigamAppBar — the top-of-viewport equivalents.