mdxui.dev
npm7.0.0-alpha.0
Alpha: Ships on npm at 7.0.0-alpha.07.0.0-alpha.0

nav

The bar at the top of a page: brand, links, one call to action and a menu that needs no script.

View as JSON
Variant
From Benchlist › homedirectoryOpen the frame

When to use

Put one nav at the top of every page of a Site. It holds the brand, up to six links and one call to action, and a budget of 96 units keeps them on one row at full width.

Choose menu: "none" for three links or fewer, or for a directory that needs a search field in the bar. Choose overlay or push when the links outgrow a phone: under the collapse width a link to #menu opens the menu, with no script.

Label each link with the noun a reader looks for: Pricing, Docs, Blog.

Use instead

No neighbor does this job.

The record

pages/benchlist/home.json, section 0
{
  "kind": "nav",
  "shell": { "inset": "bleed", "density": "none", "surface": "glass", "sticky": true },
  "block": {
    "type": "nav",
    "menu": "none",
    "brand": { "href": "/", "text": "Benchlist", "mark": "layout-grid" },
    "links": [
      ["/city/duluth", "Duluth"],
      ["/about", "About"]
    ],
    "cta": { "href": "/list-a-bench", "label": "List a bench" },
    "search": { "action": "/city/duluth", "placeholder": "Kiln, lathe, loom, press" }
  }
}

Smallest that parses

{
  "type": "nav",
  "menu": "none",
  "brand": { "href": "/", "text": "Benchlist" },
  "links": []
}

Fields and bounds

From @mdxui/site@7.0.0-alpha.0. A count reads as min–max × item; a string bound is its maximum length in characters, and links its refusal.

menu: "overlay" | "push"

PropType and boundRequired
menu"overlay" | "push"yes
collapse820 | 880yes
brandobjectyes
brand.hrefstring ≤160yes
brand.textstring ≤16no
brand.markicon or mark name (52)no
brand.suffixstring ≤8no
brand.tilebooleanno
links0–6 × [string ≤160, string ≤20]yes
ctaobjectno
cta.hrefstring ≤160yes
cta.labelstring ≤24yes
PropType and boundRequired
menu"none"yes
brandobjectyes
brand.hrefstring ≤160yes
brand.textstring ≤16no
brand.markicon or mark name (52)no
brand.suffixstring ≤8no
brand.tilebooleanno
links0–3 × [string ≤160, string ≤20]yes
ctaobjectno
cta.hrefstring ≤160yes
cta.labelstring ≤24yes
searchobjectno
search.actionstring ≤160yes
search.placeholderstring ≤40yes
search.querystring ≤120no
search.clearstring ≤160no

Variants and counts

The menu is the variant: none, overlay or push. The search field comes with none only.

navopen
menu noneopen
menu overlayopen
menu pushopen

One record in five Themes

directoryBenchlist’s ownopen
certificateopen
vaultlineopen
quaypointopen
callboardopen

Shells

paperopen
tintopen
plateopen
glassopen

In three Businesses

Carried by every Template. Seen on pages/benchlist/home.json, section 0.

Benchlist › home · directoryA directory puts search in the bar, because finding a bench is the job.
Diffkeel › home · certificateA developer tool links install and docs, so the first command is one tap away.
Harbor tides › home · quaypointAn API product links its plans, integrations and blog, and asks the reader to talk.

Do and do not

Doopen
Three short links and one call fit the row with room to spare.
Don’trefused
{
  "type": "nav",
  "menu": "overlay",
  "collapse": 880,
  "brand": {
    "href": "/sites/harbor/",
    "text": "Harbor tides",
    "mark": "waves"
  },
  "links": [
    [
      "/sites/harbor/pricing",
      "Pricing and plans"
    ],
    [
      "/sites/harbor/integrations",
      "Integrations"
    ],
    [
      "/sites/harbor/blog",
      "The tide blog"
    ],
    [
      "/sites/harbor/contact",
      "Harbor masters"
    ],
    [
      "/sites/harbor/terms",
      "Terms of use"
    ],
    [
  … 9 more lines
SectionSchema.safeParse(record)blocka bar's row holds 96 units (its link labels, 3 a link, and twice the wider of the brand and the button); shorten a label or drop a link
Six long labels and a call overrun the 96-unit row, so the record is refused.
Doopen
The call names the one thing the bar asks a reader to do.
Don’topen
A call that repeats a link spends the row twice on one address.

Accessibility

Check, on the exemplar renderLimitNowPass
Skipped heading levels00yes
Unnamed nav landmarks00 of 1yes
Scroll regions a keyboard cannot reach00 of 0yes
Copy controls that announce the resultall0 of 0yes
Images and icons with no text alternative00yes

Text pairs below AA across the 5 Themes and every scheme they emit: 5. See Render checks.

  • Landmark The nav renders the page header with one nav named Primary inside it. A skip link to main comes first.
  • Heading level The bar carries no heading. The brand is a link home, never the h1.
  • Focus order Tab runs skip link, brand, links in record order, then the call. Under the collapse width the menu link takes the place of the row.

No neighbor does this job.