IconButtonLink is mainly used as navigational element.

Complete documentation for IconButtonLink coming soon. See IconButton documentation page
Figma:

Responsive:

Adaptive:

Props

Component props
Name
Type
Default
accessibilityLabel
Required
string
-

Label for screen readers to announce IconButtonLink.

href
Required
string
-

Specifies a link URL.

active
"page" | "section"
-

When set to 'page' or 'section', it displays the item in "active" state. See the active state guidelines to learn more.

bgColor
"transparent" | "transparentDarkGray" | "gray" | "lightGray" | "white" | "red"
-

Primary colors to apply to the IconButtonLink background.

dangerouslySetSvgPath
{
  __path: string;
}
-

Defines a new icon different from the built-in Gestalt icons.

dataTestId
string
-

Available for testing purposes, if needed. Consider better queries before using this prop.

disabled
boolean
-

When disabled, IconButtonLink looks inactive and cannot be interacted with.

focusColor
"lightBackground" | "darkBackground"
-

Indicates whether this component is hosted in a light or dark container.
Used for improving focus ring color contrast.

icon
"360" | "3d" | "3d-move" | "accessibility" | "ad" | "ad-group" | "add" | "add-circle" | "add-layout" | "add-pin" | "add-section" | "ads-overview" | "ads-stats" | "alert" | "align-bottom" | "align-bottom-center" | "align-bottom-left" | "align-bottom-right" | "align-middle" | "align-top" | "align-top-center" | "align-top-left" | "align-top-right" | "alphabetical" | "android-share" | "angled-pin" | "animate" | "api" | "apple" | "apps" | "ar-try-on" | "arrow-back" | "arrow-circle-back" | "arrow-circle-down" | "arrow-circle-forward" | "arrow-circle-up" | "arrow-counter-clockwise" | "arrow-double-back" | "arrow-double-forward" | "arrow-down" | "arrow-end" | "arrow-forward" | "arrow-left-curved" | "arrow-nested" | "arrow-start" | "arrow-up" | "arrow-up-left" | "arrow-up-right" | "arrows-vertical" | "aspect-ratio" | "audio-bars" | "audio-mix" | "audio-playing" | "bell" | "bell-fill" | "birthday-cake" | "board" | "board-sticker-large" | "board-sticker-small" | "border" | "border-shadow" | "briefcase" | "building-business" | "business-hierarchy" | "calendar" | "calendar-check" | "camera" | "camera-flip" | "camera-roll" | "cancel" | "canonical-pin" | "captions" | "captions-outline" | "card-stack" | "check" | "check-circle" | "check-circle-fill" | "chevron-down-circle" | "chevron-left-circle" | "chevron-right-circle" | "chevron-up-circle" | "circle" | "circle-ellipsis" | "circle-information-fill" | "circle-initializing" | "clear" | "clips" | "clock" | "clock-checked" | "cloud-server" | "code" | "code-check" | "cog" | "collage" | "collapse" | "color" | "color-palette" | "color-picker" | "color-solid" | "color-split" | "compass" | "compose" | "contrast" | "conversion-tag" | "copy-to-clipboard" | "credit-card" | "crop" | "crystal-ball" | "cutout" | "dash" | "data-source" | "design" | "desktop" | "diagnostics" | "directional-arrow-left" | "directional-arrow-right" | "download" | "drag-drop" | "draw" | "dropbox" | "duplicate" | "edit" | "ellipsis" | "envelope" | "erase" | "erase-auto" | "etsy" | "expand" | "eye" | "eye-hide" | "face-happy" | "face-neutral" | "face-sad" | "face-smiley" | "face-smiley-outline" | "face-smiley-plus" | "face-tryon" | "facebook" | "fade" | "file-box" | "file-unknown" | "fill-opaque" | "fill-transparent" | "filter" | "flag" | "flame" | "flash" | "flash-automatic" | "flash-slash" | "flashlight" | "flip-horizontal" | "flip-vertical" | "folder" | "folder-fill" | "forward" | "gauge" | "ghost" | "ghost-fill" | "gif" | "gif-visual" | "gift" | "globe" | "globe-checked" | "gmail" | "graph-bar" | "graph-pie" | "hand" | "hand-pointing" | "handle" | "heart" | "heart-broken" | "heart-health" | "heart-outline" | "highlights" | "history" | "home" | "home-fill" | "idea-pin" | "image-portrait" | "impressum" | "indent" | "info-circle" | "information" | "insights-audience" | "insights-conversion" | "instagram" | "invoice" | "kakao-talk" | "key" | "knoop" | "lab-flask" | "lasso-magic" | "layers-stack" | "layout" | "lightbulb" | "lightning-bolt-circle" | "link" | "link-broken" | "lips" | "list-numbered" | "list-numbered-rtl" | "location" | "lock" | "logo-large" | "logo-small" | "logout" | "magic-pen" | "magic-wand" | "magnifying-glass-sparkle" | "manage-access" | "margins-large" | "margins-medium" | "margins-small" | "maximize" | "megaphone" | "menu" | "messenger" | "microphone" | "minimize" | "mobile" | "moon" | "move-pin" | "music-off" | "music-on" | "mute" | "mute-fill" | "orientation-landscape" | "orientation-portrait" | "outdent" | "outlook" | "overlay-text" | "overlay-text-outline" | "overview" | "paper-clip" | "paper-lines-plus" | "pause" | "pen" | "pen-auto" | "people" | "performance-plus" | "person" | "person-add" | "person-fill" | "person-magnifying-glass" | "phone" | "pin" | "pin-hide" | "pincode" | "pinterest" | "play" | "protect" | "question-mark" | "record-limit" | "record-limit-10" | "record-limit-15" | "record-limit-30" | "record-limit-5" | "record-limit-60" | "redo" | "refresh" | "remove" | "reorder-images" | "replace" | "report" | "rewind" | "ribbon" | "rocketship" | "rotate" | "saturation" | "save-outline" | "saved" | "scale" | "scissors" | "search" | "search-by-image" | "search-fill" | "security" | "select" | "send" | "shadows" | "shapes" | "share" | "shopping-bag" | "shrink" | "shuffles" | "skintone" | "slide" | "smiley" | "snapchat" | "sort-ascending" | "sort-descending" | "sound" | "sound-fill" | "sound-slash" | "sound-slash-fill" | "sparkle" | "speech" | "speech-ellipsis" | "speech-ellipsis-fill" | "speech-exclamation-point" | "speech-heart" | "speech-outline" | "speed" | "speed-.3x" | "speed-.5x" | "speed-1x" | "speed-2x" | "speed-3x" | "spread" | "star" | "star-half" | "star-outline" | "sticker" | "sticker-image" | "sun" | "swap" | "switch-account" | "table" | "tag" | "tag-star" | "target" | "telegram" | "template" | "terms" | "text" | "text-align-center" | "text-align-left" | "text-align-right" | "text-all-caps" | "text-extra-small" | "text-invert" | "text-large" | "text-line-height" | "text-medium" | "text-sentence-case" | "text-size" | "text-small" | "text-spacing" | "text-sticker" | "thumbs-down" | "thumbs-up" | "timer" | "timer-10" | "timer-3" | "trash-can" | "trending" | "undo" | "unlock" | "upload-feed" | "viber" | "video-advance-10-seconds" | "video-camera" | "video-rewind-10-seconds" | "view-type-default" | "view-type-dense" | "view-type-list" | "view-type-sparse" | "visit" | "warmth" | "wave" | "whatsapp" | "wifi-no" | "workflow-status-all" | "workflow-status-canceled" | "workflow-status-halted" | "workflow-status-in-progress" | "workflow-status-ok" | "workflow-status-problem" | "workflow-status-queued" | "workflow-status-unstarted" | "workflow-status-warning" | "x-social" | "yahoo" | "youtube"
-

SVG icon from the Gestalt icon library to use within Icon.

See the icon library to explore available options.

iconColor
"gray" | "darkGray" | "red" | "white" | "brandPrimary"
-

Primary color to apply to the Icon.

onClick
(arg1: {
  event: React.MouseEvent<HTMLAnchorElement> | React.KeyboardEvent<HTMLAnchorElement>;
  dangerouslyDisableOnNavigation: () => void;
}) => void
-

Callback fired when the component is clicked, pressed or tapped. See GlobalEventsHandlerProvider to learn more about link navigation.

padding
1 | 2 | 3 | 4 | 5
-

Sets a padding for the IconButtonLink.

rel
"none" | "nofollow"
-

Specifies the relationship between the current document and the linked document.

size
"xs" | "sm" | "md" | "lg" | "xl"
"lg"

The maximum height and width of IconButtonLink.

tabIndex
-1 | 0
0

Removes IconButtonLink from sequential keyboard navigation to improve accessibility.

target
null | "self" | "blank"
-

Define the frame or window to open the anchor defined on `href`.

tooltip
{
  accessibilityLabel?: string;
  inline?: boolean;
  idealDirection?: "up" | "right" | "down" | "left";
  text: string;
  zIndex?: Indexable;
}
-

Adds a Tooltip on hover/focus of the IconButtonLink.

Usage guidelines

See IconButton for usage guidelines.

Accessibility

Active state

IconButtonLink has an "active" state that visually identifies it. To set them to "active" set 'active="page"' (page redirect) or 'active="section"'. Use routing hooks from React.Router or other frameworks to identify the current route. For example, if the current pathname matches the IconButtonLink href, set IconButtonLink to "page". Use the example below as a reference.

import React from 'react';
import { Flex, IconButtonLink } from 'gestalt';

export default function Example() {
  const reactRouterPath = '/iconbuttonlink';

  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <IconButtonLink
        accessibilityLabel="Visit the Gestalt documentation"
        active={reactRouterPath === '/iconbuttonlink' ? 'page' : undefined}
        href="https://gestalt.pinterest.systems/web/iconbuttonlink#Active-item"
        icon="visit"
        onClick={({ event, dangerouslyDisableOnNavigation }) => {
          event.preventDefault();
          dangerouslyDisableOnNavigation();
        }}
        target="blank"
      />
    </Flex>
  );
}

Localization

Be sure to localize all text strings. Note that localization can lengthen text by 20 to 30 percent.

IconButtonLink depends on DefaultLabelProvider for internal text strings. Localize the texts via DefaultLabelProvider. Learn more
import { DefaultLabelProvider, Flex, IconButtonLink } from 'gestalt';

export default function Example() {
  return (
    <DefaultLabelProvider
      labels={{
        Link: {
          accessibilityNewTabLabel: 'Öffnet eine neue Browser-Registerkarte.',
          accessibilityDownloadLabel: 'Es lädt eine Datei herunter.',
        },
      }}
    >
      <Flex
        alignItems="center"
        height="100%"
        justifyContent="center"
        width="100%"
      >
        <IconButtonLink
          accessibilityLabel=""
          href="#"
          icon="visit"
          onClick={({ event, dangerouslyDisableOnNavigation }) => {
            event.preventDefault();
            dangerouslyDisableOnNavigation();
          }}
          target="blank"
          tooltip={{ text: 'Besuchen Sie Pinterest' }}
        />
      </Flex>
    </DefaultLabelProvider>
  );
}

Variants

See IconButton for more variants.

States

IconButton's appearance can be modified by the following states:

  1. enabled
  2. active
  3. disabled
    Disabled state, used to indicate that the button is not currently available for interaction.
import React from 'react';
import { Flex, IconButtonLink } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <IconButtonLink
        accessibilityLabel="Visit the Gestalt documentation"
        href="https://gestalt.pinterest.systems/web/iconbuttonlink#Active-item"
        icon="visit"
        onClick={({ event, dangerouslyDisableOnNavigation }) => {
          event.preventDefault();
          dangerouslyDisableOnNavigation();
        }}
        target="blank"
      />
    </Flex>
  );
}

import React from 'react';
import { Flex, IconButtonLink } from 'gestalt';

export default function Example() {
  const reactRouterPath = '/iconbuttonlink';

  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <IconButtonLink
        accessibilityLabel="Visit the Gestalt documentation"
        active={reactRouterPath === '/iconbuttonlink' ? 'page' : undefined}
        href="https://gestalt.pinterest.systems/web/iconbuttonlink#Active-item"
        icon="visit"
        onClick={({ event, dangerouslyDisableOnNavigation }) => {
          event.preventDefault();
          dangerouslyDisableOnNavigation();
        }}
        target="blank"
      />
    </Flex>
  );
}

import React from 'react';
import { Flex, IconButtonLink } from 'gestalt';

export default function Example() {
  const reactRouterPath = '/iconbuttonlink';

  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <IconButtonLink
        accessibilityLabel="Visit the Gestalt documentation"
        disabled
        href="https://gestalt.pinterest.systems/web/iconbuttonlink#Active-item"
        icon="visit"
        onClick={({ event, dangerouslyDisableOnNavigation }) => {
          event.preventDefault();
          dangerouslyDisableOnNavigation();
        }}
        target="blank"
      />
      <IconButtonLink
        accessibilityLabel="Visit the Gestalt documentation"
        active={reactRouterPath === '/iconbuttonlink' ? 'page' : undefined}
        disabled
        href="https://gestalt.pinterest.systems/web/iconbuttonlink#Active-item"
        icon="visit"
        onClick={({ event, dangerouslyDisableOnNavigation }) => {
          event.preventDefault();
          dangerouslyDisableOnNavigation();
        }}
        target="blank"
      />
    </Flex>
  );
}

Focus ring on dark backgrounds

IconButtonLink can be used on dark backgrounds. The focus ring is visible on dark backgrounds to ensure accessibility.

import { Box, Flex, IconButtonLink } from 'gestalt';

export default function Example() {
  return (
    <Flex gap={6}>
      <Flex direction="column" gap={6}>
        <Flex direction="column">
          <Box
            alignItems="center"
            dangerouslySetInlineStyle={{
              __style: {
                backgroundImage: 'url("https://i.ibb.co/rcdDzVh/image.png")',
              },
            }}
            display="flex"
            height="100%"
            justifyContent="center"
            padding={8}
          >
            <IconButtonLink
              accessibilityLabel="Go to Pinterest"
              focusColor="lightBackground"
              href="www.pinterest.com"
              icon="visit"
              iconColor="red"
              tooltip={{
                accessibilityLabel: 'Go to Pinterest',
                text: 'Go to Pinterest',
                idealDirection: 'up',
              }}
            />
          </Box>
          focusColor=&quot;lightBackground&quot;
        </Flex>
        <Flex direction="column">
          <Box
            alignItems="center"
            dangerouslySetInlineStyle={{
              __style: {
                backgroundImage: 'url("https://i.ibb.co/DC0sQrx/image.png")',
              },
            }}
            display="flex"
            height="100%"
            justifyContent="center"
            padding={8}
          >
            <IconButtonLink
              accessibilityLabel="Go to Pinterest"
              focusColor="darkBackground"
              href="www.pinterest.com"
              icon="visit"
              iconColor="red"
              tooltip={{
                accessibilityLabel: 'Go to Pinterest',
                text: 'Go to Pinterest',
                idealDirection: 'up',
              }}
            />
          </Box>
          focusColor=&quot;darkBackground&quot;
        </Flex>
      </Flex>
      <Flex direction="column" gap={6}>
        <Flex direction="column">
          <Box
            alignItems="center"
            dangerouslySetInlineStyle={{
              __style: {
                backgroundImage: 'url("https://i.ibb.co/rcdDzVh/image.png")',
              },
            }}
            display="flex"
            height="100%"
            justifyContent="center"
            padding={8}
          >
            <IconButtonLink
              accessibilityLabel="Go to Pinterest"
              focusColor="lightBackground"
              href="www.pinterest.com"
              icon="visit"
              iconColor="red"
              tooltip={{
                accessibilityLabel: 'Go to Pinterest',
                text: 'Go to Pinterest',
                idealDirection: 'up',
              }}
            />
          </Box>
          focusColor=&quot;lightBackground&quot;
        </Flex>
        <Flex direction="column">
          <Box
            alignItems="center"
            dangerouslySetInlineStyle={{
              __style: {
                backgroundImage: 'url("https://i.ibb.co/DC0sQrx/image.png")',
              },
            }}
            display="flex"
            height="100%"
            justifyContent="center"
            padding={8}
          >
            <IconButtonLink
              accessibilityLabel="Go to Pinterest"
              focusColor="darkBackground"
              href="www.pinterest.com"
              icon="visit"
              iconColor="red"
              tooltip={{
                accessibilityLabel: 'Go to Pinterest',
                text: 'Go to Pinterest',
                idealDirection: 'up',
              }}
            />
          </Box>
          focusColor=&quot;darkBackground&quot;
        </Flex>
      </Flex>
    </Flex>
  );
}

External handlers

IconButtonLink consumes external handlers from GlobalEventsHandlerProvider.

Handlers:

See GlobalEventsHandlerProvider for more information.

Component quality checklist

Component quality checklist
Quality item
Status
Status description
Figma Library
Ready
Component is available in Figma for web and mobile web.
Responsive Web
Ready
Component responds to changing viewport sizes in web and mobile web.

Internal documentation

GlobalEventsHandlerProvider
GlobalEventsHandlerProvider allows external link navigation control across all children components with link behavior.
See GlobalEventsHandlerProvider to learn more about link navigation.