IconButtonLink is mainly used as navigational element.
Complete documentation for IconButtonLink coming soon. See IconButton documentation page
Props
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:
enabledactivedisabled
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="lightBackground" </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="darkBackground" </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="lightBackground" </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="darkBackground" </Flex> </Flex> </Flex> ); }
External handlers
IconButtonLink consumes external handlers from GlobalEventsHandlerProvider.
Handlers:
- onNavigation: executed when IconButtonLink is clicked
See GlobalEventsHandlerProvider for more information.
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
PDocs available
Related
GlobalEventsHandlerProvider
GlobalEventsHandlerProvider allows external link navigation control across all children components with link behavior.
See
GlobalEventsHandlerProvider to learn more about link navigation.