🧭 Nav

<nav> is a responsive navigation bar that Clera positions automatically based on the current layout. You declare where it should appear at each breakpoint using HTML attributes. Clera handles the rest.

---

📋 Basic structure

Place <nav> as a direct child of <app>, at the same level as your pages.

<app>
  <nav default="bottom" desktop="left">
    <tab page="home">Home</tab>
    <tab page="search">Search</tab>
    <tab page="profile">Profile</tab>
  </nav>

  <page name="home">...</page>
  <page name="search">...</page>
  <page name="profile">...</page>
</app>

<nav> must be a direct child of <app>. Nested navs are not supported.

---

📍 Position attributes

Control where <nav> appears by setting layout-named attributes on it. Each attribute accepts a position value. Clera reads the attribute that matches the current layout tier.

Attribute	When it applies
mobile	Viewport 0 to 599px
tablet	Viewport 600px to 1023px
desktop	Viewport 1024px and above
default	Fallback when no layout-specific attribute is present

Position values:

Value	Result
"top"	Pinned to the top of the app
"bottom"	Pinned to the bottom of the app
"left"	Fixed to the left edge, full height
"right"	Fixed to the right edge, full height
"none"	Hidden at this layout

<!-- Bottom on mobile and tablet, left sidebar on desktop -->
<nav default="bottom" desktop="left">
  ...
</nav>

<!-- Hidden on mobile, top bar on tablet and desktop -->
<nav mobile="none" default="top">
  ...
</nav>

<!-- Always on the left -->
<nav default="left">
  ...
</nav>

default is evaluated when no attribute matches the current layout. If no position is resolved at all, Clera leaves the <nav> completely alone and applies no positioning or click binding.

---

🔗 Navigation items

Use <tab> elements inside <nav>. Any <tab> with a page attribute navigates to that page when clicked.

<nav default="bottom" desktop="left">
  <tab page="home">
    <span>Home</span>
  </tab>
  <tab page="library">
    <span>Library</span>
  </tab>
  <tab page="settings">
    <span>Settings</span>
  </tab>
</nav>

Tabs with an action attribute fire an action instead of navigating:

<tab action="openSearch">Search</tab>

---

🎨 Styling nav

Clera sets a position attribute on <nav> to reflect the resolved position at the current layout. Use it in CSS to style nav elements based on where the nav is placed.

/* Style the nav when it is at the bottom */
nav[position="bottom"] {
  background: #fff;
  border-top: 1px solid #e0e0e0;
  height: 64px;
}

/* Style the nav when it is on the left */
nav[position="left"] {
  background: #1a1a2e;
  width: 220px;
}

/* Tabs inside a left nav */
nav[position="left"] tab {
  padding: 12px 20px;
  color: #fff;
}

Clera also sets a --item-direction CSS variable on <nav>:

• column when the nav is at top or bottom (icon above label)

• row when the nav is on the left or right (icon beside label)

Use it to orient tab content automatically:

nav[position] tab {
  flex-direction: var(--item-direction, column);
}

---

↕️ Collapsed state

Navs at left or right positions support a collapsed state. When collapsed, the nav is visually narrowed. You control what “collapsed” looks like in CSS using the [collapsed] attribute Clera sets.

nav[position="left"] {
  width: 220px;
  transition: width 0.2s ease;
}

nav[position="left"][collapsed] {
  width: 64px;
  overflow: hidden;
}

nav[position="left"][collapsed] .nav-label {
  display: none;
}

Toggle the collapsed state from JavaScript using the nav API:

app.expand("nav");    // removes [collapsed]
app.collapse("nav");  // adds [collapsed]
app.toggle("nav");    // flips between the two

The selector passed to expand, collapse, and toggle is a standard CSS selector applied within <app>. Pass any selector that uniquely identifies your nav.

// If you have multiple navs, target by id
app.collapse("#mainNav");
app.toggle(".sidebar-nav");

---

🔁 Multiple navs

You can have more than one <nav> inside <app>. Each one resolves its position independently. If two navs would resolve to the same position at the same time, Clera logs a NAV_POSITION_CONFLICT warning in dev mode and leaves the conflicting nav in place unchanged.

<!-- Primary nav: bottom on mobile, left on desktop -->
<nav id="mainNav" default="bottom" desktop="left">
  <tab page="home">Home</tab>
  <tab page="explore">Explore</tab>
</nav>

<!-- Secondary nav: only visible on desktop, at the top -->
<nav id="topBar" mobile="none" tablet="none" desktop="top">
  <tab action="openSearch">Search</tab>
  <tab action="openAccount">Account</tab>
</nav>

<page name="home">...</page>
<page name="explore">...</page>

---

Next

17 Sidebar