{
  "name": "NavItem",
  "source": "src/components/NavItem.tsx",
  "propsType": "NavItemProps",
  "description": "Nav Item renders an `<a>` when given `href`, a `<button>` otherwise —\nchosen by what the caller is actually building, the same judgment call\nMenu and Select make. A primary nav bar is links; a nav item with\n`showChevron` that opens a menu (no `href` of its own) is a button.\n\nInteraction state comes from React Aria rather than CSS pseudo-classes,\nmatching Button: `useHover` is pointer-aware so a tap does not stay\n\"hovered\" until the next tap elsewhere, and `useFocusRing` shows the ring\nonly for keyboard navigation. The CSS keeps its own `:hover` /\n`:focus-visible` rules so the stylesheet still works without React.",
  "import": "import { NavItem } from 'ionbase-ui';",
  "status": "stable",
  "summary": "A primary navigation destination. Renders an <a> when given `href`, a <button> otherwise.",
  "useWhen": [
    "building a header nav bar, a sidebar or a section switcher",
    "an item opens a menu rather than navigating — pass `showChevron` and no `href`"
  ],
  "useInstead": [
    {
      "when": "the link sits inside body copy or a content block",
      "use": "Link"
    },
    {
      "when": "it is a row in a dropdown list rather than a top-level destination",
      "use": "MenuItem"
    }
  ],
  "slots": {
    "icon": {
      "accepts": "Icon",
      "note": "leading icon; omit its `label` — the item's text names it"
    }
  },
  "a11y": {
    "role": "link when `href` is set, button when it is not",
    "guarantees": [
      "hover state comes from React Aria's pointer-aware `useHover`, so a tap does not stay hovered until the next tap elsewhere",
      "the focus ring shows for keyboard navigation only",
      "the CSS keeps its own `:hover` / `:focus-visible` rules, so the styling survives without React",
      "`isCurrent` sets `aria-current=\"page\"`, and the current item is marked by an underline as well as colour, which survives forced-colours mode"
    ],
    "requires": [
      "an accessible name — `children`, or `aria-label` on an icon-only item"
    ],
    "notes": [
      "NavItem is one item, not the landmark. Wrap the set in a <nav> with its own accessible name."
    ]
  },
  "antiPatterns": [
    {
      "dont": "`showChevron` on a plain link that navigates",
      "why": "the chevron promises a menu; nothing opens"
    },
    {
      "dont": "marking the current page with colour only",
      "do": "`aria-current=\"page\"`",
      "why": "a screen-reader user is otherwise never told where they are"
    },
    {
      "dont": "marking the current page with a className or colour of your own instead of `isCurrent`",
      "why": "a screen reader hears nothing without `aria-current`, and a colour-only marker fails anyone who cannot see the difference"
    }
  ],
  "deprecated": [
    {
      "prop": "disabled",
      "replacement": "isDisabled"
    }
  ],
  "stylesheet": "src/styles/nav-item.css",
  "tokens": [
    "--border-focus",
    "--border-primary",
    "--border-width-thick",
    "--font-family-sans",
    "--font-weight-medium",
    "--icon-disabled",
    "--icon-interactive-hover",
    "--icon-primary",
    "--icon-size-sm",
    "--icon-tertiary",
    "--ion-duration-base",
    "--ion-ease-out",
    "--radius-sm",
    "--spacing-4",
    "--spacing-8",
    "--text-default",
    "--text-disabled",
    "--text-interactive-hover",
    "--text-secondary",
    "--type-body-sm",
    "--type-body-sm-line-height"
  ],
  "props": {
    "icon": {
      "type": "React.ReactNode",
      "required": false,
      "origin": "own",
      "description": "Figma's `Icon` slot — an optional leading icon."
    },
    "showChevron": {
      "type": "boolean | undefined",
      "required": false,
      "origin": "own",
      "description": "Figma's `Show Chevron`. Set on a nav item that opens a menu, not a plain link."
    },
    "isCurrent": {
      "type": "boolean | undefined",
      "required": false,
      "origin": "own",
      "description": "The page the user is on. Marks the item `aria-current=\"page\"` and draws\nthe same indicator Tabs' underline does — so a section switcher built from\nNavItems says where you are, in words for a screen reader and in more than\ncolour for everyone else."
    },
    "isDisabled": {
      "type": "boolean | undefined",
      "required": false,
      "origin": "own"
    },
    "disabled": {
      "type": "boolean | undefined",
      "required": false,
      "origin": "own",
      "tags": {
        "deprecated": "Use `isDisabled`. Accepted as an alias for one minor version."
      }
    },
    "children": {
      "type": "React.ReactNode",
      "required": false,
      "origin": "own"
    },
    "className": {
      "type": "string | undefined",
      "required": false,
      "origin": "own"
    },
    "href": {
      "type": "string | undefined",
      "required": false,
      "origin": "own"
    }
  },
  "propCounts": {
    "own": 8,
    "aria": 0,
    "dom": 276,
    "other": 0
  }
}