{
  "name": "Link",
  "source": "src/components/Link.tsx",
  "propsType": "LinkProps",
  "description": "Link — Figma `Link` (774:1516).\n\nRenders an `<a>` when given an `href` and a `<button>` otherwise, the same\njudgment `NavItem` makes: the element follows what the caller is actually\nbuilding rather than a separate `as` prop. A link that does not navigate is\na button, and shipping one as an anchor breaks middle-click, \"open in new\ntab\" and the screen-reader announcement all at once.\n\nNO SIZE PROP, DELIBERATELY. A link is an inline element and inherits its\ntype from the text around it — `font-size: inherit` in the stylesheet, and\nicons sized in `em` so they scale with it. Figma has to draw its variants at\nsome concrete size (16/24, `type/body`), but that is one sample of an\ninheriting element, not a specification. Do not add a size ladder to match\nthe drawing.",
  "import": "import { Link } from 'ionbase-ui';",
  "status": "stable",
  "summary": "Navigation to somewhere else. Renders an <a> when given `href`, a <button> otherwise.",
  "useWhen": [
    "the interaction takes the user to a different page, view or resource",
    "the destination should support middle-click, open-in-new-tab and copy-link"
  ],
  "useInstead": [
    {
      "when": "the interaction changes something rather than going somewhere",
      "use": "Button",
      "why": "a link that does not navigate breaks middle-click, open-in-new-tab and the screen-reader announcement all at once"
    },
    {
      "when": "it is a primary navigation destination in a header or sidebar",
      "use": "NavItem"
    }
  ],
  "variants": {
    "variant": {
      "inline": {
        "use": "the default — a link inside a paragraph. Underlined in every state, because a link in body copy must not rely on colour alone (WCAG 1.4.1)"
      },
      "standalone": {
        "use": "a link that already reads as interactive from its position — a card footer, an action row. Underlines on hover only"
      }
    }
  },
  "slots": {
    "startIcon": {
      "accepts": "Icon",
      "note": "omit Icon's `label` — the link text already names it"
    },
    "endIcon": {
      "accepts": "Icon",
      "note": "the external-link or arrow affordance; same rule about `label`"
    }
  },
  "a11y": {
    "role": "link when `href` is set, button when it is not",
    "guarantees": [
      "the rendered element follows what the caller is actually building, so the announcement is always honest",
      "`inline` stays underlined in every state, so it never depends on colour alone"
    ],
    "requires": [
      "link text that makes sense read on its own — screen-reader users navigate by a list of links"
    ]
  },
  "antiPatterns": [
    {
      "dont": "\"click here\" or \"read more\" as the whole link text",
      "why": "out of context in a links list it names nothing"
    },
    {
      "dont": "adding a size prop or wrapper to scale it",
      "why": "a link is inline and inherits its type from the text around it, by design — icons are sized in `em` to follow"
    },
    {
      "dont": "`target=\"_blank\"` with no warning in the text or endIcon",
      "why": "an unannounced new tab disorients screen-reader and low-vision users"
    }
  ],
  "deprecated": [
    {
      "prop": "disabled",
      "replacement": "isDisabled"
    }
  ],
  "stylesheet": "src/styles/link.css",
  "tokens": [
    "--border-width-thick",
    "--ion-duration-base",
    "--ion-ease-out",
    "--radius-xs",
    "--ring-focus",
    "--spacing-4",
    "--text-disabled",
    "--text-link",
    "--text-link-hover",
    "--text-link-visited"
  ],
  "props": {
    "variant": {
      "type": "LinkVariant | undefined",
      "required": false,
      "origin": "own",
      "description": "Matches the Figma `Type` variant.\n\n`inline` is for links inside body copy and is underlined in every state —\na link in a paragraph must not rely on colour alone (WCAG 1.4.1).\n`standalone` is for links that already read as interactive from their\nposition, and underlines on hover only.",
      "values": [
        "inline",
        "standalone"
      ],
      "default": "inline"
    },
    "startIcon": {
      "type": "React.ReactNode",
      "required": false,
      "origin": "own",
      "description": "Optional icon before the label."
    },
    "endIcon": {
      "type": "React.ReactNode",
      "required": false,
      "origin": "own",
      "description": "Optional icon after the label — the external-link or arrow affordance."
    },
    "className": {
      "type": "string | undefined",
      "required": false,
      "origin": "own"
    },
    "children": {
      "type": "React.ReactNode",
      "required": false,
      "origin": "own"
    },
    "disabled": {
      "type": "boolean | undefined",
      "required": false,
      "origin": "own",
      "tags": {
        "deprecated": "Use `isDisabled`. Accepted as an alias for one minor version."
      }
    },
    "isDisabled": {
      "type": "boolean | undefined",
      "required": false,
      "origin": "aria",
      "description": "Whether the link is disabled."
    },
    "elementType": {
      "type": "string | undefined",
      "required": false,
      "origin": "aria",
      "description": "The HTML element used to render the link, e.g. 'a', or 'span'.",
      "tags": {
        "default": "'a'"
      }
    },
    "onPress": {
      "type": "((e: PressEvent) => void) | undefined",
      "required": false,
      "origin": "aria",
      "description": "Handler that is called when the press is released over the target."
    },
    "onPressStart": {
      "type": "((e: PressEvent) => void) | undefined",
      "required": false,
      "origin": "aria",
      "description": "Handler that is called when a press interaction starts."
    },
    "onPressEnd": {
      "type": "((e: PressEvent) => void) | undefined",
      "required": false,
      "origin": "aria",
      "description": "Handler that is called when a press interaction ends, either\nover the target or when the pointer leaves the target."
    },
    "onPressChange": {
      "type": "((isPressed: boolean) => void) | undefined",
      "required": false,
      "origin": "aria",
      "description": "Handler that is called when the press state changes."
    },
    "onPressUp": {
      "type": "((e: PressEvent) => void) | undefined",
      "required": false,
      "origin": "aria",
      "description": "Handler that is called when a press is released over the target, regardless of\nwhether it started on the target or not."
    },
    "onClick": {
      "type": "((e: MouseEvent<FocusableElement>) => void) | undefined",
      "required": false,
      "origin": "aria",
      "description": "**Not recommended – use `onPress` instead.** `onClick` is an alias for `onPress`\nprovided for compatibility with other libraries. `onPress` provides\nadditional event details for non-mouse interactions."
    },
    "autoFocus": {
      "type": "boolean | undefined",
      "required": false,
      "origin": "aria",
      "description": "Whether the element should receive focus on render."
    },
    "onFocus": {
      "type": "((e: FocusEvent<Element, Element>) => void) | undefined",
      "required": false,
      "origin": "aria",
      "description": "Handler that is called when the element receives focus."
    },
    "onBlur": {
      "type": "((e: FocusEvent<Element, Element>) => void) | undefined",
      "required": false,
      "origin": "aria",
      "description": "Handler that is called when the element loses focus."
    },
    "onFocusChange": {
      "type": "((isFocused: boolean) => void) | undefined",
      "required": false,
      "origin": "aria",
      "description": "Handler that is called when the element's focus status changes."
    },
    "onKeyDown": {
      "type": "((e: KeyboardEvent) => void) | undefined",
      "required": false,
      "origin": "aria",
      "description": "Handler that is called when a key is pressed."
    },
    "onKeyUp": {
      "type": "((e: KeyboardEvent) => void) | undefined",
      "required": false,
      "origin": "aria",
      "description": "Handler that is called when a key is released."
    },
    "href": {
      "type": "string | undefined",
      "required": false,
      "origin": "aria",
      "description": "A URL to link to. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#href)."
    },
    "hrefLang": {
      "type": "string | undefined",
      "required": false,
      "origin": "aria",
      "description": "Hints at the human language of the linked URL.\nSee[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#hreflang)."
    },
    "target": {
      "type": "HTMLAttributeAnchorTarget | undefined",
      "required": false,
      "origin": "aria",
      "description": "The target window for the link. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#target)."
    },
    "rel": {
      "type": "string | undefined",
      "required": false,
      "origin": "aria",
      "description": "The relationship between the linked resource and the current page. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel)."
    },
    "download": {
      "type": "string | boolean | undefined",
      "required": false,
      "origin": "aria",
      "description": "Causes the browser to download the linked URL. A string may be provided to suggest a file name.\nSee [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#download)."
    },
    "ping": {
      "type": "string | undefined",
      "required": false,
      "origin": "aria",
      "description": "A space-separated list of URLs to ping when the link is followed. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#ping)."
    },
    "referrerPolicy": {
      "type": "HTMLAttributeReferrerPolicy | undefined",
      "required": false,
      "origin": "aria",
      "description": "How much of the referrer to send when following the link. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#referrerpolicy).",
      "values": [
        "",
        "origin",
        "no-referrer",
        "no-referrer-when-downgrade",
        "origin-when-cross-origin",
        "same-origin",
        "strict-origin",
        "strict-origin-when-cross-origin",
        "unsafe-url"
      ]
    },
    "routerOptions": {
      "type": "undefined",
      "required": false,
      "origin": "aria",
      "description": "Options for the configured client side router."
    },
    "aria-label": {
      "type": "string | undefined",
      "required": false,
      "origin": "aria",
      "description": "Defines a string value that labels the current element."
    },
    "aria-labelledby": {
      "type": "string | undefined",
      "required": false,
      "origin": "aria",
      "description": "Identifies the element (or elements) that labels the current element."
    },
    "aria-describedby": {
      "type": "string | undefined",
      "required": false,
      "origin": "aria",
      "description": "Identifies the element (or elements) that describes the object."
    },
    "aria-details": {
      "type": "string | undefined",
      "required": false,
      "origin": "aria",
      "description": "Identifies the element (or elements) that provide a detailed, extended description for the\nobject."
    }
  },
  "propCounts": {
    "own": 6,
    "aria": 26,
    "dom": 266,
    "other": 0
  }
}