Anchor

The anchor component creates a hyperlink targeting a specific location within the same page or a different one.

import * as React from 'react';
import { Anchor } from '@itwin/itwinui-react';

export default () => {
  return <Anchor href='https://www.example.com/'>Example Site</Anchor>;
};

The anchor’s href attribute is the destination URL while the text within the anchor element should describe the link’s name.

Usage

The Anchor component is a styled wrapper over the native <a> element, and it can be used in the same way.

<Anchor href='https://example.com'>Example</Anchor>

Consider using a named anchor when you want the user to land not only on a specific page, but also to arrive at a content area that may be below the fold so the user does not have to scroll to discover it. This can be achieved using fragment links.

<Anchor href='#section1'>Section 1</Anchor>

<h2 id='section1' tabIndex={-1}>Section 1</h2>

A common question is whether to use an anchor or a button. The basic rule of thumb is an anchor takes you to another page, whereas a button performs an action. For more details, read this article on buttons vs links.

as prop

The anchor component supports the polymorphic as prop to render the anchor as a button. This can be useful when the design requires a control which visually looks like an anchor but acts like a button, i.e. it performs an action within the same page, rather than navigating to a destination URL.

import * as React from 'react';
import { Anchor } from '@itwin/itwinui-react';

export default () => {
  return (
    <Anchor as='button' onClick={() => console.log('Button clicked!')}>
      Anchor as a button
    </Anchor>
  );
};

The as prop can also be used with Link components from different routers such as Next.js and React Router

External links

A common question is whether to open external links in a new tab. The basic rule of thumb is to let the user decide, rather than deciding it for them. Opening links in new tabs by default is useful in very limited scenarios, such as when the user is filling out a form and you want to prevent data loss. For more details, refer to this NNG article.

If you do ultimately decide based on your research that it is beneficial to open links in a new tab, then you can use the target prop in addition to the isExternal prop.

• When target="_blank" is specified, iTwinUI will automatically add visually-hidden text to indicate that the link will open in a new tab. This ensures that screen-reader users are made aware of the link’s behavior, and helps satisfy WCAG SC 3.2.5.
• The isExternal prop provides a visual indication that the link will open in a new tab, for sighted users.

import * as React from 'react';
import { Anchor } from '@itwin/itwinui-react';

export default () => {
  return (
    <Anchor href='https://www.example.com/' isExternal target='_blank'>
      Example Site
    </Anchor>
  );
};

Note: Not all external links should open in a new tab. The isExternal prop is not necessary for external links that open in the same tab.

Underlines

By default, an anchor is only underlined when hovered, with a few exceptions:

1. Anchors inside a Text component are underlined by default.
2. All anchors are underlined by default when using a high-contrast theme.

For better accessibility, it is recommended to explicitly make the anchor underlined in all themes, even when used outside Text. This can be achieved using the underline prop.

import * as React from 'react';
import { Anchor } from '@itwin/itwinui-react';

export default () => {
  return (
    <Anchor href='https://www.example.com/' underline>
      Example Site
    </Anchor>
  );
};

Props