OnLinkNavigationProvider

OnLinkNavigationProvider is a React context provider to externally control the link behavior of components further down the tree.

Props

Component props
Name	Type	Default
`children` Required	`React.Node`	-
`onNavigation`	`({\| href: string, target?: null \| "self" \| "blank", \|}) => ?({\| +event: SyntheticEvent<>, \|}) => void`	-
	If passed, it replaces the default link behavior with custom on navigation behavior. See custom navigation context variant for examples.

Variants

Components with links use simple <a> tags. In order to replace the default link behavior with custom ones (e.g. react-router), onNavigation provides an interface to pass external logic into the 'onClick' event handler in children links.

This example illustrates a custom navigation implementations to externally control the link functionality of Link: setting a default navigation logic with OnLinkNavigationProvider.

If onNavigation prop is passed to OnLinkNavigationProvider, it's passed down to all children links and sets a customized default link navigation behavior. onNavigation is a higher-order function: it takes named arguments: href and target and returns an event handler function. In the component's onClick event handler, the onClick prop gets called first, followed by the function passed down by the OnLinkNavigationProvider.

If onNavigation is a hook function, it can contain complex logic, including React hooks, to perform side effects.

In this example, the useOnNavigation hook function is passed to OnLinkNavigationProvider and executes the following actions:

Disable the default link behavior
Show an alert message
Open a different URL in a new window

The returned onNavigationClick function inside the hook function uses the event access to preventDefault(). It could also be used to stopPropagation().

Accessible links in Gestalt announce to assistive technologies that the link opens in a new tab. Always make sure your external logic aligns with the 'target' prop values. For example, if your external logic opens a url in a new tab, set 'target' to 'blank'. Localize the default label with DefaultLabelProvider. Learn more

Examples from start to end: Link, Button, IconButton, TapArea

function OnNavigation() {
  const [ onNavigationMode, setOnNavigationMode ] = React.useState('default');

  const useOnNavigation = ({ href, target }) => {

    const onNavigationClick = ({ event }) => {
      event.preventDefault();
      // eslint-disable-next-line no-alert
      alert('Disabled link: '+href+'. Opening help.pinterest.com instead.');
      window.open('https://help.pinterest.com', target === 'blank' ? '_blank' : '_self');
    }

    return onNavigationClick;
  }

  const linkProps = {
    href: 'https://pinterest.com',
    target: 'blank',
  }

  return (
    <OnLinkNavigationProvider onNavigation={onNavigationMode === 'custom' ? useOnNavigation : undefined}>
      <Flex direction="column" gap={{ column: 2, row: 0 }}>
        <Flex direction="column" gap={{ column: 2, row: 0 }}>
          <Text>Navigation type:</Text>
          <RadioButton
            checked={onNavigationMode === 'default'}
            id="default1"
            label="Default Link Navigation"
            name="default"
            onChange={() => setOnNavigationMode('default')}
            value="default"
          />
          <RadioButton
            checked={onNavigationMode === 'custom'}
            id="custom1"
            label="Custom OnLinkNavigationProvider Navigation"
            name="custom"
            onChange={() => setOnNavigationMode('custom')}
            value="custom"
          />
          <Divider/>
        </Flex>
        <Flex gap={{ row: 4, column: 0 }} alignItems="center">
          <Text>
            <Link {...linkProps}>Visit pinterest.com</Link>
          </Text>
          <Box>
            <Button
              {...linkProps}
              role="link"
              text="Visit pinterest.com"
            />
          </Box>
          <IconButton
            {...linkProps}
            accessibilityLabel="Link IconButton"
            icon="visit"
            iconColor="darkGray"
            role="link"
            size="lg"
          />
          <Box width={100}>
            <TapArea
              {...linkProps}
              role="link"
              rounding={2}
            >
              <Box color="darkGray" rounding={4} borderStyle="sm">
                <Mask rounding={2}>
                  <Image
                    alt="Antelope Canyon"
                    naturalHeight={1}
                    naturalWidth={1}
                    src="https://i.ibb.co/DwYrGy6/stock14.jpg"
                  />
                </Mask>
              </Box>
            </TapArea>
          </Box>
        </Flex>
      </Flex>
    </OnLinkNavigationProvider>
  );
}

function OnNavigation() {
  const [ onNavigationMode, setOnNavigationMode ] = React.useState('default');

  const useOnNavigation = ({ href, target }) => {

    const onNavigationClick = ({ event }) => {
      event.preventDefault();
      // eslint-disable-next-line no-alert
      alert('Disabled link: '+href+'. Opening help.pinterest.com instead.');
      window.open('https://help.pinterest.com', target === 'blank' ? '_blank' : '_self');
    }

    return onNavigationClick;
  }

  const linkProps = {
    href: 'https://pinterest.com',
    target: 'blank',
  }

  return (
    <OnLinkNavigationProvider onNavigation={onNavigationMode === 'custom' ? useOnNavigation : undefined}>
      <Flex direction="column" gap={{ column: 2, row: 0 }}>
        <Flex direction="column" gap={{ column: 2, row: 0 }}>
          <Text>Navigation type:</Text>
          <RadioButton
            checked={onNavigationMode === 'default'}
            id="default1"
            label="Default Link Navigation"
            name="default"
            onChange={() => setOnNavigationMode('default')}
            value="default"
          />
          <RadioButton
            checked={onNavigationMode === 'custom'}
            id="custom1"
            label="Custom OnLinkNavigationProvider Navigation"
            name="custom"
            onChange={() => setOnNavigationMode('custom')}
            value="custom"
          />
          <Divider/>
        </Flex>
        <Flex gap={{ row: 4, column: 0 }} alignItems="center">
          <Text>
            <Link {...linkProps}>Visit pinterest.com</Link>
          </Text>
          <Box>
            <Button
              {...linkProps}
              role="link"
              text="Visit pinterest.com"
            />
          </Box>
          <IconButton
            {...linkProps}
            accessibilityLabel="Link IconButton"
            icon="visit"
            iconColor="darkGray"
            role="link"
            size="lg"
          />
          <Box width={100}>
            <TapArea
              {...linkProps}
              role="link"
              rounding={2}
            >
              <Box color="darkGray" rounding={4} borderStyle="sm">
                <Mask rounding={2}>
                  <Image
                    alt="Antelope Canyon"
                    naturalHeight={1}
                    naturalWidth={1}
                    src="https://i.ibb.co/DwYrGy6/stock14.jpg"
                  />
                </Mask>
              </Box>
            </TapArea>
          </Box>
        </Flex>
      </Flex>
    </OnLinkNavigationProvider>
  );
}

Examples from top to bottom: Callout, Upsell, ActivationCard

function OnNavigation() {
  const [ onNavigationMode, setOnNavigationMode ] = React.useState('default');

  const useOnNavigation = ({ href, target }) => {

    const onNavigationClick = ({ event }) => {
      event.preventDefault();
      // eslint-disable-next-line no-alert
      alert('Disabled link: '+href+'. Opening help.pinterest.com instead.');
      window.open('https://help.pinterest.com', target === 'blank' ? '_blank' : '_self');
    }

    return onNavigationClick;
  }

  const linkProps = {
    href: 'https://pinterest.com',
    target: 'blank',
  }

  return (
    <OnLinkNavigationProvider onNavigation={onNavigationMode === 'custom' ? useOnNavigation : undefined}>
      <Flex direction="column" gap={{ column: 2, row: 0 }}>
        <Flex direction="column" gap={{ column: 2, row: 0 }}>
          <Text>Navigation type:</Text>
          <RadioButton
            checked={onNavigationMode === 'default'}
            id="default2"
            label="Default Link Navigation"
            name="default"
            onChange={() => setOnNavigationMode('default')}
            value="default"
          />
          <RadioButton
            checked={onNavigationMode === 'custom'}
            id="custom"
            label="Custom OnLinkNavigationProvider Navigation"
            name="custom2"
            onChange={() => setOnNavigationMode('custom')}
            value="custom"
          />
          <Divider/>
        </Flex>
        <Flex direction="column" gap={{ column: 4, row: 0 }} alignItems="center">
          <Callout
            type="info"
            iconAccessibilityLabel="Info icon"
            title="Your business account was created!"
            message="Apply to the Verified Merchant Program!"
            primaryAction={
              { ...linkProps,
                label:'Get started',
                accessibilityLabel: 'Get started: verified merchant program'
              }}
            secondaryAction={
              { ...linkProps,
                label: 'Learn more',
                accessibilityLabel: 'Learn more: verified merchant program'
              }}
            dismissButton={{
              accessibilityLabel: 'Dismiss banner',
              onDismiss: () => {},
            }}
          />
          <Upsell
            title="Give $30, get $60 in ads credit"
            message="Earn $60 of ads credit, and give $30 of ads credit to a friend"
            primaryAction={
              { ...linkProps,
                label: 'Send invite',
                accessibilityLabel: 'Send invite for ads credit'
              }}
            dismissButton={{
              accessibilityLabel: 'Dismiss banner',
              onDismiss: () => {},
            }}
            imageData={{
              component: <Icon icon="pinterest" accessibilityLabel="Pin" color="default" size={32}/>
            }}
          />
          <ActivationCard
            status="notStarted"
            statusMessage="Not started"
            title="Claim your website"
            message="Grow distribution and track Pins linked to your website"
            link={{
              ...linkProps,
              label: 'Claim your website now',
              accessibilityLabel: '',
            }}
            dismissButton={{
              accessibilityLabel: 'Dismiss card',
              onDismiss: ()=>{},
            }}
          />
        </Flex>
      </Flex>
    </OnLinkNavigationProvider>
  );
}

function OnNavigation() {
  const [ onNavigationMode, setOnNavigationMode ] = React.useState('default');

  const useOnNavigation = ({ href, target }) => {

    const onNavigationClick = ({ event }) => {
      event.preventDefault();
      // eslint-disable-next-line no-alert
      alert('Disabled link: '+href+'. Opening help.pinterest.com instead.');
      window.open('https://help.pinterest.com', target === 'blank' ? '_blank' : '_self');
    }

    return onNavigationClick;
  }

  const linkProps = {
    href: 'https://pinterest.com',
    target: 'blank',
  }

  return (
    <OnLinkNavigationProvider onNavigation={onNavigationMode === 'custom' ? useOnNavigation : undefined}>
      <Flex direction="column" gap={{ column: 2, row: 0 }}>
        <Flex direction="column" gap={{ column: 2, row: 0 }}>
          <Text>Navigation type:</Text>
          <RadioButton
            checked={onNavigationMode === 'default'}
            id="default2"
            label="Default Link Navigation"
            name="default"
            onChange={() => setOnNavigationMode('default')}
            value="default"
          />
          <RadioButton
            checked={onNavigationMode === 'custom'}
            id="custom"
            label="Custom OnLinkNavigationProvider Navigation"
            name="custom2"
            onChange={() => setOnNavigationMode('custom')}
            value="custom"
          />
          <Divider/>
        </Flex>
        <Flex direction="column" gap={{ column: 4, row: 0 }} alignItems="center">
          <Callout
            type="info"
            iconAccessibilityLabel="Info icon"
            title="Your business account was created!"
            message="Apply to the Verified Merchant Program!"
            primaryAction={
              { ...linkProps,
                label:'Get started',
                accessibilityLabel: 'Get started: verified merchant program'
              }}
            secondaryAction={
              { ...linkProps,
                label: 'Learn more',
                accessibilityLabel: 'Learn more: verified merchant program'
              }}
            dismissButton={{
              accessibilityLabel: 'Dismiss banner',
              onDismiss: () => {},
            }}
          />
          <Upsell
            title="Give $30, get $60 in ads credit"
            message="Earn $60 of ads credit, and give $30 of ads credit to a friend"
            primaryAction={
              { ...linkProps,
                label: 'Send invite',
                accessibilityLabel: 'Send invite for ads credit'
              }}
            dismissButton={{
              accessibilityLabel: 'Dismiss banner',
              onDismiss: () => {},
            }}
            imageData={{
              component: <Icon icon="pinterest" accessibilityLabel="Pin" color="default" size={32}/>
            }}
          />
          <ActivationCard
            status="notStarted"
            statusMessage="Not started"
            title="Claim your website"
            message="Grow distribution and track Pins linked to your website"
            link={{
              ...linkProps,
              label: 'Claim your website now',
              accessibilityLabel: '',
            }}
            dismissButton={{
              accessibilityLabel: 'Dismiss card',
              onDismiss: ()=>{},
            }}
          />
        </Flex>
      </Flex>
    </OnLinkNavigationProvider>
  );
}

With a Dropdown

function OnNavigation() {
  const [ onNavigationMode, setOnNavigationMode ] = React.useState('default');
  const [open, setOpen] = React.useState(false);
  const [selected, setSelected] = React.useState(null);
  const anchorRef = React.useRef(null);
  const handleSelect = ({item}) => {
    setSelected(item);
  };

  const useOnNavigation = ({ href, target }) => {

    const onNavigationClick = ({ event }) => {
      event.preventDefault();
      // eslint-disable-next-line no-alert
      alert('Disabled link: '+href+'. Opening help.pinterest.com instead.');
      window.open('https://help.pinterest.com', target === 'blank' ? '_blank' : '_self');
    }

    return onNavigationClick;
  }

  const linkProps = {
    href: 'https://pinterest.com',
    target: 'blank',
  }

  return (
    <OnLinkNavigationProvider onNavigation={onNavigationMode === 'custom' ? useOnNavigation : undefined}>
      <Flex direction="column" gap={{ column: 2, row: 0 }}>
        <Flex direction="column" gap={{ column: 2, row: 0 }}>
          <Text>Navigation type:</Text>
          <RadioButton
            checked={onNavigationMode === 'default'}
            id="default3"
            label="Default Link Navigation"
            name="default"
            onChange={() => setOnNavigationMode('default')}
            value="default"
          />
          <RadioButton
            checked={onNavigationMode === 'custom'}
            id="custom3"
            label="Custom OnLinkNavigationProvider Navigation"
            name="custom"
            onChange={() => setOnNavigationMode('custom')}
            value="custom"
          />
          <Divider/>
        </Flex>
        <Box display="flex" justifyContent="center">
          <Button
            accessibilityControls="basic-dropdown-example"
            accessibilityHaspopup
            accessibilityExpanded={open}
            iconEnd="arrow-down"
            text="Menu"
            ref={anchorRef}
            selected={open}
            onClick={ () => setOpen((prevVal) => !prevVal) }
          />
          {open && (
            <Dropdown id="basic-dropdown-example" anchor={anchorRef.current} onDismiss={() => {setOpen(false)}}>
              <Dropdown.Item
                { ...linkProps }
                isExternal
                option={{ value: 'item 3', label: 'Item 3 with a really long, detailed, complex name' }}
              />
            </Dropdown>
          )}
        </Box>
      </Flex>
    </OnLinkNavigationProvider>
  );
}

function OnNavigation() {
  const [ onNavigationMode, setOnNavigationMode ] = React.useState('default');
  const [open, setOpen] = React.useState(false);
  const [selected, setSelected] = React.useState(null);
  const anchorRef = React.useRef(null);
  const handleSelect = ({item}) => {
    setSelected(item);
  };

  const useOnNavigation = ({ href, target }) => {

    const onNavigationClick = ({ event }) => {
      event.preventDefault();
      // eslint-disable-next-line no-alert
      alert('Disabled link: '+href+'. Opening help.pinterest.com instead.');
      window.open('https://help.pinterest.com', target === 'blank' ? '_blank' : '_self');
    }

    return onNavigationClick;
  }

  const linkProps = {
    href: 'https://pinterest.com',
    target: 'blank',
  }

  return (
    <OnLinkNavigationProvider onNavigation={onNavigationMode === 'custom' ? useOnNavigation : undefined}>
      <Flex direction="column" gap={{ column: 2, row: 0 }}>
        <Flex direction="column" gap={{ column: 2, row: 0 }}>
          <Text>Navigation type:</Text>
          <RadioButton
            checked={onNavigationMode === 'default'}
            id="default3"
            label="Default Link Navigation"
            name="default"
            onChange={() => setOnNavigationMode('default')}
            value="default"
          />
          <RadioButton
            checked={onNavigationMode === 'custom'}
            id="custom3"
            label="Custom OnLinkNavigationProvider Navigation"
            name="custom"
            onChange={() => setOnNavigationMode('custom')}
            value="custom"
          />
          <Divider/>
        </Flex>
        <Box display="flex" justifyContent="center">
          <Button
            accessibilityControls="basic-dropdown-example"
            accessibilityHaspopup
            accessibilityExpanded={open}
            iconEnd="arrow-down"
            text="Menu"
            ref={anchorRef}
            selected={open}
            onClick={ () => setOpen((prevVal) => !prevVal) }
          />
          {open && (
            <Dropdown id="basic-dropdown-example" anchor={anchorRef.current} onDismiss={() => {setOpen(false)}}>
              <Dropdown.Item
                { ...linkProps }
                isExternal
                option={{ value: 'item 3', label: 'Item 3 with a really long, detailed, complex name' }}
              />
            </Dropdown>
          )}
        </Box>
      </Flex>
    </OnLinkNavigationProvider>
  );
}

Link / Button / IconButton / TapArea / DropDown / Callout / Upsell / ActivationCard
If these components are under a OnLinkNavigationProvider, their link behavior defaults to the logic defined in OnLinkNavigationProvider. In order to disable the onNavigation logic, we can return "dangerouslyDisableOnNavigation" in the onClick callback. See each component page for more information.

Component quality checklist

Component quality checklist
Quality item	Status	Status description
Figma Library		Component is not currently available in Figma.
Responsive Web	Ready	Component is available in code for web and mobile web.
iOS		Component is not currently available in code for iOS.
Android		Component is not currently available in code for Android.

Edit page on GitHub

; Opens a new tab

OnLinkNavigationProvider

Props

Variants

Custom link navigation context

Related

Component quality checklist