Hyperlink API - React Magma

Links are used as navigational elements and can be used on their own or inline with text.

Usage Guidelines

When to use

Use links when you want users to:

Navigate to a different page within the application
Navigate to an entirely different site
Jump to an element on the same page
Link to emails or phone numbers

When not to use

Use a 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 should never be used for navigational actions. See button docs for further information.

Basic Usage

Links provide a lightweight option for navigation but like other interactive elements, too many links will clutter a page and make it difficult for users to identify their next steps. This is especially true for inline links, which should be used sparingly.

import React from 'react';

import { Hyperlink } from 'react-magma-dom';

export function Example() {
  return (
    <Hyperlink opensInNewTab to="https://www.google.com">
      Google
    </Hyperlink>
  );
}

StyledAs

Sometimes links can be styled as buttons in order to give them more weight on the page, but this is only on the surface. Underneath the styles, they are still a link component. The styledAs prop can be used to style the Hyperlink component as another component. The options are Link (default) and Button.

import React from 'react';

import {
  ButtonColor,
  ButtonTextTransform,
  Hyperlink,
  Spacer,
  SpacerAxis,
} from 'react-magma-dom';

export function Example() {
  return (
    <>
      <Hyperlink
        textTransform={ButtonTextTransform.none}
        styledAs="Button"
        opensInNewTab
        to="https://www.google.com"
      >
        Google
      </Hyperlink>
      <Spacer size="8" axis={SpacerAxis.horizontal} />
      <Hyperlink
        color={ButtonColor.secondary}
        textTransform={ButtonTextTransform.none}
        styledAs="Button"
        opensInNewTab
        to="https://www.google.com"
      >
        Google
      </Hyperlink>
      <Spacer size="8" axis={SpacerAxis.horizontal} />
      <Hyperlink
        color={ButtonColor.danger}
        styledAs="Button"
        opensInNewTab
        to="https://www.google.com"
      >
        Google
      </Hyperlink>
      <Spacer size="8" axis={SpacerAxis.horizontal} />
      <Hyperlink
        color={ButtonColor.marketing}
        styledAs="Button"
        opensInNewTab
        to="https://www.google.com"
      >
        Google
      </Hyperlink>
    </>
  );
}

Opens in New Tab

Use the opensInNewTab prop to make links open in a new browser tab or window. This automatically adds the necessary accessibility attributes (target="_blank", rel="noopener noreferrer") and screen reader text ("Opens in a new tab") to ensure the link is secure and accessible.

import React from 'react';

import { Hyperlink, Spacer, SpacerAxis } from 'react-magma-dom';

export function Example() {
  return (
    <>
      <Hyperlink to="https://www.google.com">Same Tab Link</Hyperlink>
      <Spacer size="12" axis={SpacerAxis.horizontal} />
      <Hyperlink opensInNewTab to="https://www.google.com">
        New Tab Link
      </Hyperlink>
      <Spacer size="12" axis={SpacerAxis.horizontal} />
      <Hyperlink styledAs="Button" opensInNewTab to="https://www.google.com">
        Button Style New Tab
      </Hyperlink>
    </>
  );
}

Icon

import React from 'react';

import {
  Hyperlink,
  HyperlinkIconPosition,
  magma,
  Spacer,
  SpacerAxis,
  Paragraph,
  Flex,
  FlexBehavior,
  FlexJustify,
  TypographyVisualStyle,
} from 'react-magma-dom';
import {
  KeyboardArrowLeftIcon,
  KeyboardArrowRightIcon,
  CalendarTodayIcon,
  OpenInNewIcon,
} from 'react-magma-icons';

export function Example() {
  return (
    <>
      <Flex
        behavior={FlexBehavior.container}
        justify={FlexJustify.spaceBetween}
      >
        <span style={{ flex: '0 0 auto' }}>
          <Hyperlink
            opensInNewTab
            to="./"
            hasUnderline={false}
            icon={<KeyboardArrowLeftIcon aria-hidden />}
            iconPosition={HyperlinkIconPosition.left}
          >
            Back
          </Hyperlink>
        </span>
        <span style={{ flex: '0 0 auto' }}>
          <Hyperlink
            opensInNewTab
            to="./"
            hasUnderline={false}
            icon={<KeyboardArrowRightIcon aria-hidden />}
            iconPosition={HyperlinkIconPosition.right}
          >
            Next
          </Hyperlink>
        </span>
      </Flex>
      <Spacer size={'8px'} axis={SpacerAxis.both} />
      <Hyperlink
        styledAs="Button"
        opensInNewTab
        to="./"
        icon={<KeyboardArrowLeftIcon aria-hidden />}
        iconPosition={HyperlinkIconPosition.left}
      >
        Back
      </Hyperlink>
      <Spacer size={'8px'} axis={SpacerAxis.horizontal} />
      <Hyperlink
        styledAs="Button"
        opensInNewTab
        to="./"
        icon={[
          <KeyboardArrowLeftIcon aria-hidden key={0} />,
          <KeyboardArrowRightIcon aria-hidden key={1} />,
        ]}
        iconPosition={HyperlinkIconPosition.both}
      >
        Guess
      </Hyperlink>
      <Spacer size={'8px'} axis={SpacerAxis.horizontal} />
      <Hyperlink
        styledAs="Button"
        opensInNewTab
        to="./"
        icon={<KeyboardArrowRightIcon aria-hidden />}
        iconPosition={HyperlinkIconPosition.right}
      >
        Next
      </Hyperlink>
      <Spacer size={'8px'} axis={SpacerAxis.both} />
      <Paragraph visualStyle={TypographyVisualStyle.headingSmall}>
        <Hyperlink
          opensInNewTab
          to="https://www.google.com"
          hasUnderline={false}
          icon={[
            <CalendarTodayIcon
              key={0}
              size={magma.iconSizes.xLarge}
              style={{ marginRight: magma.spaceScale.spacing03 }}
              aria-hidden
            />,
            <OpenInNewIcon
              key={1}
              size={magma.iconSizes.xLarge}
              style={{ marginLeft: magma.spaceScale.spacing03 }}
              aria-hidden
            />,
          ]}
          iconPosition={HyperlinkIconPosition.both}
        >
          Schedule an appointment
        </Hyperlink>
      </Paragraph>
      <Paragraph visualStyle={TypographyVisualStyle.bodyLarge}>
        <Hyperlink
          opensInNewTab
          to="https://www.google.com"
          hasUnderline={false}
          icon={[
            <CalendarTodayIcon
              key={0}
              size={magma.iconSizes.large}
              aria-hidden
            />,
            <OpenInNewIcon key={1} size={magma.iconSizes.large} aria-hidden />,
          ]}
          iconPosition={HyperlinkIconPosition.both}
        >
          Schedule an appointment
        </Hyperlink>
      </Paragraph>
      <Paragraph visualStyle={TypographyVisualStyle.bodySmall}>
        <Hyperlink
          opensInNewTab
          to="https://www.google.com"
          hasUnderline={false}
          icon={[
            <CalendarTodayIcon
              key={0}
              size={magma.iconSizes.small}
              aria-hidden
            />,
            <OpenInNewIcon key={1} size={magma.iconSizes.small} aria-hidden />,
          ]}
          iconPosition={HyperlinkIconPosition.both}
        >
          Schedule an appointment
        </Hyperlink>
      </Paragraph>
      <Paragraph visualStyle={TypographyVisualStyle.bodyXSmall}>
        <Hyperlink
          opensInNewTab
          to="https://www.google.com"
          hasUnderline={false}
          icon={[
            <CalendarTodayIcon
              key={0}
              size={magma.iconSizes.xSmall}
              aria-hidden
            />,
            <OpenInNewIcon key={1} size={magma.iconSizes.xSmall} aria-hidden />,
          ]}
          iconPosition={HyperlinkIconPosition.both}
        >
          Schedule an appointment
        </Hyperlink>
      </Paragraph>
    </>
  );
}

hasUnderline

The underline text decoration can be turned off. When a hyperlink is used within other elements like paragraphs, the underline is still mandatory.

import React from 'react';

import {
  Hyperlink,
  Spacer,
  SpacerAxis,
  magma,
  HyperlinkIconPosition,
} from 'react-magma-dom';
import { OpenInNewIcon } from 'react-magma-icons';

export function Example() {
  return (
    <>
      <Hyperlink
        opensInNewTab
        to="https://www.google.com"
        hasUnderline={false}
        icon={<OpenInNewIcon size={magma.iconSizes.small} aria-hidden />}
        iconPosition={HyperlinkIconPosition.right}
      >
        Google
      </Hyperlink>
      <Spacer size={'8px'} axis={SpacerAxis.both} />
      Cupcake ipsum dolor sit amet wafer biscuit toffee. Chocolate bar brownie
      lemon drops tootsie roll pudding muffin powder pudding.{' '}
      <Hyperlink
        opensInNewTab
        to="https://sallysbakingaddiction.com/triple-chocolate-layer-cake/"
      >
        I love chocolate cake
      </Hyperlink>{' '}
      Pastry dragée cheesecake chocolate bar donut jujubes candy canes sugar
      plum bonbon. Toffee pie macaroon apple pie gummi bears gummi bears
      shortbread.
    </>
  );
}

Render Props Usage

Use this when you want to render something that is from another library. For example, the Link component from react-router.

import React from 'react';

import { Hyperlink } from 'react-magma-dom';

// We support Link components from libraries such as react-router/reach-router/gatsby that use the `to` prop in place of `href`
const Link = ({ to, ...rest }) => <a href={to} {...rest} />;

export function Example() {
  return (
    <Hyperlink styledAs="Button" to="./">
      {linkProps => <Link {...linkProps}>Render Props Google</Link>}
    </Hyperlink>
  );
}

Inverse

isInverse is an optional boolean prop, that may be passed in when the hyperlink is to be displayed on a dark background.

import React from 'react';

import { Card, CardBody, Hyperlink, Paragraph } from 'react-magma-dom';

export function Example() {
  return (
    <Card isInverse>
      <CardBody>
        <Paragraph>
          <Hyperlink isInverse opensInNewTab to="https://www.google.com">
            Google inverse link
          </Hyperlink>
        </Paragraph>
        <Hyperlink
          isInverse
          styledAs="Button"
          opensInNewTab
          to="https://www.google.com"
        >
          Inverse link styled as button
        </Hyperlink>
      </CardBody>
    </Card>
  );
}

Hyperlink Props

This component uses forwardRef. The ref is applied to the a element.

All of the standard anchor attributes can be provided as props and will be applied to the a element that gets rendered.

children

Required

Description

The content of the component

Type

React.ReactNode

Default

color

Description

The color of the button, indicating its function in the UI

Type

enum, one of:
ButtonColor.danger
ButtonColor.marketing
ButtonColor.primary
ButtonColor.secondary
ButtonColor.subtle
ButtonColor.success

Default

ButtonColor.primary

hasUnderline

Type

boolean

Default

icon

Description

Icon to display within the component

Type

ReactElement | Array

Default

iconPosition

Description

Position within the link for the icon to appear

Type

enum, one of:
HyperlinkIconPosition.both
HyperlinkIconPosition.left
HyperlinkIconPosition.right

Default

HyperlinkIconPosition.right

isFullWidth

Description

Set the button to display full-width.

Type

boolean

Default

false

isInverse

Description

If true, the component will have inverse styling to better appear on a dark background

Type

boolean

Default

false

isLoading

Description

Set the button to a loading state

Type

boolean

Default

false

opensInNewTab

Description

If true, the link will be opened in a new tab

Type

boolean

Default

false

shape

Description

Defines the border radius

Type

enum, one of:
ButtonShape.fill
ButtonShape.leftCap
ButtonShape.rightCap
ButtonShape.round

Default

ButtonShape.fill

size

Description

The relative size of the button

Type

enum, one of:
ButtonSize.large
ButtonSize.medium
ButtonSize.small

Default

ButtonSize.medium

styledAs

Description

How the hyperlink is styled (can look like either a plain link or a button)

Type

Default

textTransform

Description

Determines whether the button appears in all-caps

Type

enum, one of:
ButtonTextTransform.none
ButtonTextTransform.uppercase

Default

ButtonTextTransform.uppercase

Required

Description

The href value of the link

Type

string

Default

variant

Description

The variant of the button

Type

enum, one of:
ButtonVariant.link
ButtonVariant.solid

Default

ButtonVariant.solid

On this page

Design

Components

Patterns

Data Visualization

Hyperlink

Usage Guidelines

When to use

When not to use

Basic Usage

StyledAs

Opens in New Tab

Icon

hasUnderline

Render Props Usage

Inverse

Hyperlink Props