Link

The Link component allows you to show links on the page, open them in a new window, and change the color.

Props

Name	Type	Default
`href` Required	`string`	-
`accessibilityLabel`	`string`	-
	Supply a short, descriptive label for screen-readers to replace link texts that don't provide sufficient context about the link component behavior. Texts like `Click Here,` or `Read More` can be confusing when a screen reader reads them out of context. In those cases, we must pass an alternative text to replace the link text. Accessibility: It populates aria-label. Screen readers read the `accessibilityLabel` prop, if present, instead of the link text.
`accessibilitySelected`	`boolean`	-
`children`	`React.Node`	-
`hoverStyle`	`"none" \| "underline"`	`"underline"`
`id`	`string`	-
	id attribute of the anchor tag
`inline`	`boolean`	`false`
`onBlur`	`() => void`	-
`onClick`	`AbstractEventHandler<SyntheticMouseEvent<HTMLAnchorElement> \| SyntheticKeyboardEvent<HTMLAnchorElement>, {\| disableOnNavigation: () => void \|}>`	-
	Callback fired when Link is clicked (pressed and released) with a mouse or keyboard. See custom navigation variant for examples.
`onFocus`	`() => void`	-
`ref`	`React.Ref<"a">`	-
	Forward the ref to the underlying anchor element
`rel`	`"none" \| "nofollow"`	`"none"`
`role`	`"tab"`	-
`rounding`	`"pill" \| "circle" \| 0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8`	`"0"`
`tapStyle`	`"none" \| "compress"`	`"none"`
`target`	`"null" \| "self" \| "blank"`	`"null"`

Usage guidelines

When to Use

For navigation within or directly accompanying a sentence.
Directing users to another page or a different portion of the same page.

When Not to Use

Performing actions, such as "Save", "Cancel" or "Delete". Use Button instead.
Submitting a form or opening a modal. Use Button instead.

Example

You should wrap Link components inside of a Text component to get the correct font & underline color.

Incorrect underline color: Pinterest.com

Correct underline color: Pinterest.com

<Box>
  <Link href="https://pinterest.com">
    <Box padding={2}>
      <Text color="red" weight="bold">
        Incorrect underline color: Pinterest.com
      </Text>
    </Box>
  </Link>
  <Text color="red" weight="bold">
    <Link href="https://pinterest.com">
      <Box padding={2}>Correct underline color: Pinterest.com</Box>
    </Link>
  </Text>
</Box>

<Box>
  <Link href="https://pinterest.com">
    <Box padding={2}>
      <Text color="red" weight="bold">
        Incorrect underline color: Pinterest.com
      </Text>
    </Box>
  </Link>
  <Text color="red" weight="bold">
    <Link href="https://pinterest.com">
      <Box padding={2}>Correct underline color: Pinterest.com</Box>
    </Link>
  </Text>
</Box>

Accessible Content

When providing the content for the link, avoid phrases like "click here" or "go to".

Bad ❌

For more information, click here.

Good ✅

Visit Pinterest.com for more information.

<Box>
  <Heading>Bad ❌</Heading>
  <Text>
    For more information,{' '}
    <Text inline weight="bold">
      <Link accessibilityLabel="visit https://pinterest.com" inline href="https://pinterest.com">
        click here
      </Link>
    </Text>
    .
  </Text>
  <Box paddingY={4}>
    <Heading>Good ✅</Heading>
    <Text>
      Visit{' '}
      <Text inline weight="bold">
        <Link inline href="https://pinterest.com">
          Pinterest.com
        </Link>
      </Text>{' '}
      for more information.
    </Text>
  </Box>
</Box>

<Box>
  <Heading>Bad ❌</Heading>
  <Text>
    For more information,{' '}
    <Text inline weight="bold">
      <Link accessibilityLabel="visit https://pinterest.com" inline href="https://pinterest.com">
        click here
      </Link>
    </Text>
    .
  </Text>
  <Box paddingY={4}>
    <Heading>Good ✅</Heading>
    <Text>
      Visit{' '}
      <Text inline weight="bold">
        <Link inline href="https://pinterest.com">
          Pinterest.com
        </Link>
      </Text>{' '}
      for more information.
    </Text>
  </Box>
</Box>

Accessible Tab Link

Use accessibilitySelected and role when using it as a Tab.

Boards

Pins

function TabExample() {
  const [activeIndex, setActiveIndex] = React.useState(0);
  return (
    <Box display="flex" alignItems="center" role="tablist">
      {['Boards', 'Pins'].map((text, index) => (
        <Box
          color={index === activeIndex ? 'darkGray' : undefined}
          display="inlineBlock"
          key={text}
          rounding="pill"
        >
          <Link
            accessibilitySelected={index === activeIndex}
            hoverStyle="none"
            href="https://pinterest.com"
            onClick={({ event }) => {
              event.preventDefault();
              setActiveIndex(index);
            }}
            rounding="pill"
            role="tab"
          >
            <Box padding={3} rounding="pill">
              <Text color={index === activeIndex ? 'white' : 'darkGray'}>{text}</Text>
            </Box>
          </Link>
        </Box>
      ))}
    </Box>
  );
}

function TabExample() {
  const [activeIndex, setActiveIndex] = React.useState(0);
  return (
    <Box display="flex" alignItems="center" role="tablist">
      {['Boards', 'Pins'].map((text, index) => (
        <Box
          color={index === activeIndex ? 'darkGray' : undefined}
          display="inlineBlock"
          key={text}
          rounding="pill"
        >
          <Link
            accessibilitySelected={index === activeIndex}
            hoverStyle="none"
            href="https://pinterest.com"
            onClick={({ event }) => {
              event.preventDefault();
              setActiveIndex(index);
            }}
            rounding="pill"
            role="tab"
          >
            <Box padding={3} rounding="pill">
              <Text color={index === activeIndex ? 'white' : 'darkGray'}>{text}</Text>
            </Box>
          </Link>
        </Box>
      ))}
    </Box>
  );
}

Permutations: tapStyle and hoverStyle

Link without compress nor underline

Link with compress only

Link with underline only

Link with compress and underline

function PermutationsExample() {
  return (
    <Box>
      {[
        { text: 'Link without compress nor underline', hoverStyle: 'none', tapStyle: 'none' },
        { text: 'Link with compress only', hoverStyle: 'none', tapStyle: 'compress' },
        { text: 'Link with underline only', hoverStyle: 'underline', tapStyle: 'none' },
        { text: 'Link with compress and underline', hoverStyle: 'underline', tapStyle: 'compress' },
      ].map(({ text, hoverStyle, tapStyle }) => (
        <Box key={text} padding={2}>
          <Text>
            <Link
              hoverStyle={hoverStyle}
              href="https://pinterest.com"
              onClick={({ event }) => {
                event.preventDefault();
              }}
              tapStyle={tapStyle}
              target="blank"
            >
              {text}
            </Link>
          </Text>
        </Box>
      ))}
    </Box>
  );
}

function PermutationsExample() {
  return (
    <Box>
      {[
        { text: 'Link without compress nor underline', hoverStyle: 'none', tapStyle: 'none' },
        { text: 'Link with compress only', hoverStyle: 'none', tapStyle: 'compress' },
        { text: 'Link with underline only', hoverStyle: 'underline', tapStyle: 'none' },
        { text: 'Link with compress and underline', hoverStyle: 'underline', tapStyle: 'compress' },
      ].map(({ text, hoverStyle, tapStyle }) => (
        <Box key={text} padding={2}>
          <Text>
            <Link
              hoverStyle={hoverStyle}
              href="https://pinterest.com"
              onClick={({ event }) => {
                event.preventDefault();
              }}
              tapStyle={tapStyle}
              target="blank"
            >
              {text}
            </Link>
          </Text>
        </Box>
      ))}
    </Box>
  );
}

Variants

This example illustrates two custom navigation implementations to externally control the link navigation behavior of Link: setting a default logic with OnLinkNavigationProvider and a custom component logic with the onClick prop.

If onNavigation prop is passed to OnLinkNavigationProvider, it's passed down to all children links and sets a custom default link navigation behavior. onLinkNavigation is a higher-order function: it takes named arguments (href and target) and returns an event handler function. In the component's onClick event handler, the onClick prop gets called first, followed by the function passed down by the OnLinkNavigationProvider.

Link's onClick prop is an event handler function. This callback takes 2 named parameters: 'event', the 'onClick' event, and disableOnNavigation, a callback function that disables any default custom navigation logic set by OnLinkNavigationProvider. disableOnNavigation is only accessible in OnLinkNavigationProvider's children components with link behavior.

In this example, Link has a parent OnLinkNavigationProvider setting a default custom navigation logic. We can compare three navigation behaviors: (a) the default Link behavior (by disabling the OnLinkNavigationProvider's inherited logic), (b) the default custom behavior set by OnLinkNavigationProvider and (c) a custom behavior set on Link.

onClick is used to disable the default custom logic set in OnLinkNavigationProvider and implement custom behavior at the component level. disableOnNavigation and customOnNavigation are both called first during the 'onClick' event.

If onNavigation is a custom hook function, it can contain complex logic, including React hooks, to perform side effects.

In this example, both onNavigation and customOnNavigation functions execute the following actions:

Disable the default link behavior
Show an alert message
Open a different URL in a new window

Both onNavigationClick, inside onNavigation, and onClick have event access to preventDefault(). It could also be used to stopPropagation().

Navigation controller:

Default navigation (disabled custom navigation set on OnLinkNavigationProvider)

Custom navigation set on OnLinkNavigationProvider

Custom navigation set on Link

Visit pinterest.com

function OnNavigation() {
  const [onNavigationMode, setOnNavigationMode] = React.useState('provider_disabled');

  const onNavigation = ({ href, target }) => {
    const onNavigationClick = ({ event }) => {
      event.preventDefault();
      // eslint-disable-next-line no-alert
      alert('CUSTOM NAVIGATION set on <OnLinkNavigationProvider onNavigation/>. Disabled link: '+href+'. Opening business.pinterest.com instead.');
      window.open('https://business.pinterest.com', target === 'blank' ? '_blank' : '_self');
    };
    return onNavigationClick;
  };

  const customOnNavigation = () => {
    // eslint-disable-next-line no-alert
    alert(
      'CUSTOM NAVIGATION set on <Link onClick/>. Disabled link: https://pinterest.com. Opening help.pinterest.com instead.',
    );
    window.open('https://help.pinterest.com', '_blank');
  };

  const onClickHandler = ({ event, disableOnNavigation }) => {
    if (onNavigationMode === 'provider_disabled') {
      disableOnNavigation();
    } else if (onNavigationMode === 'link_custom') {
      event.preventDefault();
      disableOnNavigation();
      customOnNavigation();
    }
  };

  const linkProps = {
    href: 'https://pinterest.com',
    onClick: onClickHandler,
    target: 'blank',
  };

  return (
    <OnLinkNavigationProvider onNavigation={onNavigation}>
      <Flex direction="column" gap={2}>
        <Flex direction="column" gap={2}>
          <Text>Navigation controller:</Text>
          <RadioButton
            checked={onNavigationMode === 'provider_disabled'}
            id="provider_disabled"
            label="Default navigation (disabled custom navigation set on OnLinkNavigationProvider)"
            name="navigation"
            onChange={() => setOnNavigationMode('provider_disabled')}
            value="provider_disabled"
          />
          <RadioButton
            checked={onNavigationMode === 'provider_custom'}
            id="provider_custom"
            label="Custom navigation set on OnLinkNavigationProvider"
            name="navigation"
            onChange={() => setOnNavigationMode('provider_custom')}
            value="provider_custom"
          />
          <RadioButton
            checked={onNavigationMode === 'link_custom'}
            id="link_custom"
            label="Custom navigation set on Link"
            name="navigation"
            onChange={() => setOnNavigationMode('link_custom')}
            value="link_custom"
          />
          <Divider />
        </Flex>
        <Text>
          <Link {...linkProps}>Visit pinterest.com</Link>
        </Text>
      </Flex>
    </OnLinkNavigationProvider>
  );
}

function OnNavigation() {
  const [onNavigationMode, setOnNavigationMode] = React.useState('provider_disabled');
  const onNavigation = ({ href, target }) => {
    const onNavigationClick = ({ event }) => {
      event.preventDefault();
      // eslint-disable-next-line no-alert
      alert('CUSTOM NAVIGATION set on <OnLinkNavigationProvider onNavigation/>. Disabled link: '+href+'. Opening business.pinterest.com instead.');
      window.open('https://business.pinterest.com', target === 'blank' ? '_blank' : '_self');
    };
    return onNavigationClick;
  };
  const customOnNavigation = () => {
    // eslint-disable-next-line no-alert
    alert(
      'CUSTOM NAVIGATION set on <Link onClick/>. Disabled link: https://pinterest.com. Opening help.pinterest.com instead.',
    );
    window.open('https://help.pinterest.com', '_blank');
  };
  const onClickHandler = ({ event, disableOnNavigation }) => {
    if (onNavigationMode === 'provider_disabled') {
      disableOnNavigation();
    } else if (onNavigationMode === 'link_custom') {
      event.preventDefault();
      disableOnNavigation();
      customOnNavigation();
    }
  };
  const linkProps = {
    href: 'https://pinterest.com',
    onClick: onClickHandler,
    target: 'blank',
  };
  return (
    <OnLinkNavigationProvider onNavigation={onNavigation}>
      <Flex direction="column" gap={2}>
        <Flex direction="column" gap={2}>
          <Text>Navigation controller:</Text>
          <RadioButton
            checked={onNavigationMode === 'provider_disabled'}
            id="provider_disabled"
            label="Default navigation (disabled custom navigation set on OnLinkNavigationProvider)"
            name="navigation"
            onChange={() => setOnNavigationMode('provider_disabled')}
            value="provider_disabled"
          />
          <RadioButton
            checked={onNavigationMode === 'provider_custom'}
            id="provider_custom"
            label="Custom navigation set on OnLinkNavigationProvider"
            name="navigation"
            onChange={() => setOnNavigationMode('provider_custom')}
            value="provider_custom"
          />
          <RadioButton
            checked={onNavigationMode === 'link_custom'}
            id="link_custom"
            label="Custom navigation set on Link"
            name="navigation"
            onChange={() => setOnNavigationMode('link_custom')}
            value="link_custom"
          />
          <Divider />
        </Flex>
        <Text>
          <Link {...linkProps}>Visit pinterest.com</Link>
        </Text>
      </Flex>
    </OnLinkNavigationProvider>
  );
}

OnLinkNavigationProvider
OnLinkNavigationProvider allows external link navigation control across all children components with link behavior.
See custom navigation variant for examples.

Edit page on GitHub