---
id: link-overlay
category: navigation
title: Link Overlay
package: '@chakra-ui/layout'
description:
  'Link overlay is a semantic component used to wrap elements (cards, blog
  posts, articles, etc.) in a link.'
---

## Import

```js
import { LinkBox, LinkOverlay } from '@chakra-ui/react'
```

## Usage

When you need to link an entire component or card, it can be tempting to wrap it
within `<a href="...">` and think you're done. This is considered **unsemantic
and incorrect** because the component or card could contain other clickable
elements or links (tags, timestamps, buttons).

> [According to the specification](https://www.w3.org/TR/html5/text-level-semantics.html#the-a-element),
> an `<a>` element’s content model specifically states that an `<a>` cannot
> contain any interactive descendants (button, anchors, input, etc.).

The `LinkOverlay` component aims to solve this by overlaying one link on top of
the component or card, and then elevating the remaining links on top of it.

Wrap the container within a `LinkBox` and use the `LinkOverlay` as a child of it
or around the title's content.

```jsx
<LinkBox as='article' maxW='sm' p='5' borderWidth='1px' rounded='md'>
  <Box as='time' dateTime='2021-01-15 15:30:00 +0000 UTC'>
    13 days ago
  </Box>
  <Heading size='md' my='2'>
    <LinkOverlay href='#'>
      New Year, New Beginnings: Smashing Workshops & Audits
    </LinkOverlay>
  </Heading>
  <Text>
    Catch up on what’s been cookin’ at Smashing and explore some of the most
    popular community resources.
  </Text>
</LinkBox>
```

### Nested Links

The `LinkBox` lifts any nested links to the top using `z-index` to ensure proper
keyboard navigation between links.

> Use the keyboard to test how focus ring moves within the article

```jsx
<LinkBox as='article' maxW='sm' p='5' borderWidth='1px' rounded='md'>
  <Box as='time' dateTime='2021-01-15 15:30:00 +0000 UTC'>
    13 days ago
  </Box>
  <Heading size='md' my='2'>
    <LinkOverlay href='#'>
      New Year, New Beginnings: Smashing Workshops & Audits
    </LinkOverlay>
  </Heading>
  <Text mb='3'>
    Catch up on what’s been cookin’ at Smashing and explore some of the most
    popular community resources.
  </Text>
  <Box as='a' color='teal.400' href='#inner-link' fontWeight='bold'>
    Some inner link
  </Box>
</LinkBox>
```

## Usage with Routing Library

To add support for external libraries like Next.js' or gatsby `Link`, you can
wrap them around the `LinkOverlay` or use the `as` prop (for reach and react
router)

```jsx live=false
import NextLink from 'next/link'

function Example() {
  return (
    <LinkBox as='article'>
      <h2>
        <LinkOverlay as={NextLink} href='#'>
          Some blog post
        </LinkOverlay>
      </h2>
      <p>
        As a side note, using quotation marks around an attribute value is
        required only if this value is not a valid identifier.
      </p>
      <a href='#inner-link'>Some inner link</a>
    </LinkBox>
  )
}
```

## Caveat

One of the side-effects of this technique is that the content can't be
"selectable" (i.e. with a pointing device), however, this seems to be pretty
trivial compared to the benefits!