# Link
> Link is mainly used as navigational element and usually appear within or directly following a paragraph or sentence.

## Import

```js
import { Link } from '@gemini-suite/vera-react';
```

## Examples

### Basic

Use `Link` when you want users to navigate to a different page within the application or jump to an existing element on the same page. Links usually appear within or directly following a sentence.

<Callout variant="tip">

Use a [Button component](/components/button) instead of a link for actions that will change data or manipulate how it is displayed, change a state, or trigger an action. Buttons perform an action, like submitting a form or closing a modal; Links take you somewhere, like to the documentation page.

</Callout>

```jsx
<Box>
  Did you know that you can{' '}
  <Link href="#api-reference">{'jump to API Reference'}</Link>?
</Box>
```

### External link

When you link to an entirely different site which is placed outside the current host, mark it with `isExternal` flag.

The rel and target will automatically be updated to `rel=”noreferrer noopener”` `target="_blank"` (link will open a new tab) and an external icon will be shown.

```jsx
<Box>
  <Link href="https://www.geminisuite.com" isExternal>
    Gemini Suite
  </Link>{' '}
  is a leading technology supplier and enabler for Europe's green energy
  transition.
</Box>
```

### Disabled link

```jsx
<Flex flow="column">
  <Box>
    This is some text with an{' '}
    <Link href="#" isDisabled>
      {'Inactive link'}
    </Link>
    .
  </Box>
  <Box>
    <Link href="https://www.powel.com/" isDisabled isExternal>
      {'www.powel.com'}
    </Link>{' '}
    has been shut down with the moment the Gemini Suite was founded.
  </Box>
</Flex>
```

### Link with content

By default, links are styled with color cue and an underline, but sometimes you may want to wrap certain elements with `Link` to provide navigational semantics without impacting their appearance. Use `bare` prop to remove the default styling.

```jsx
<Link
  href="#torvald-halvor-profile"
  bare
  className="dB maw5"
  css={{
    padding: '$spacingM',
    borderRadius: '$m',
    border: '1px solid $borderNeutralSubtle',
    '&:hover, &:focus': {
      borderColor: '$borderAccentBold'
    }
  }}
>
  <Flex flow="column">
    <FlexItem as={Flex}>
      <Avatar.Root of="Torvald Halvor">
        <Avatar.Image src="https://images.unsplash.com/photo-1552058544-f2b08422138a?ixlib=rb-1.2.1&amp;q=80&amp;fm=jpg&amp;crop=faces&amp;fit=crop&amp;h=200&amp;w=200&amp;ixid=eyJhcHBfaWQiOjE3Nzg0fQ" />
        <Avatar.Fallback>
          <Avatar.Initials />
        </Avatar.Fallback>
      </Avatar.Root>
      <Flex flow="column" gap="none">
        <Box as="h4">Torvald Halvor</Box>
        <Box as="h6">Head of department</Box>
      </Flex>
    </FlexItem>
    <FakeText words="10" />
  </Flex>
</Link>
```

---

## API Reference

| Name         | Type                                                      | Default | Description                                                                                                                                                                                                                                                                                  | Required |
| ------------ | --------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `as`         | `keyof JSX.IntrinsicElements \| React.ComponentType<any>` | `a`     | Change the component to a different HTML tag or custom component. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.   For more details, read our [Composition](/get-started/composition#polymorphism) guide. |          |
| `css`        | `StitchesCss`                                             |         | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries or variants.                                                 |          |
| `href`       | `string`                                                  |         | URL to be used for the link. The `href` is passed to the underlying `<a>` element. If `as` is specified, the link behavior may need different props such as `onClick`.                                                                                                                       |          |
| `isExternal` | `boolean`                                                 | `false` | When `isExternal` is set to `true`, icon next to link content is rendered. Proper `target` and `rel` attributes are added to element. The link will open in new tab.                                                                                                                         |          |
| `isDisabled` | `boolean`                                                 | `false` | When `true`, the link is inactive. Pointer events on the element are ignored.                                                                                                                                                                                                                |          |
| `bare`       | `boolean`                                                 | `false` | When `true`, default link styles are removed.                                                                                                                                                                                                                                                |          |