or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

custom-events.mdindex.mdoutbound-link.mdplugin-configuration.md
tile.json

outbound-link.mddocs/

OutboundLink Component

React component for tracking clicks on external links with automatic gtag event firing and intelligent navigation handling.

Capabilities

OutboundLink React Component

Enhanced anchor component that automatically tracks outbound link clicks as gtag events.

import * as React from "react";

/**
 * OutboundLink component that tracks external link clicks
 * Extends standard HTML anchor element with automatic event tracking
 * Implemented as a React.forwardRef for ref forwarding support
 */
declare const OutboundLink: React.ForwardRefExoticComponent<
  OutboundLinkProps & React.HTMLProps<HTMLAnchorElement> & React.RefAttributes<HTMLAnchorElement>
>;

interface OutboundLinkProps {
  /** Optional click handler called before gtag event tracking */
  onClick?: (event: React.MouseEvent<HTMLAnchorElement>) => void;
}

Usage Examples:

Basic Usage

import React from "react";
import { OutboundLink } from "gatsby-plugin-google-gtag";

export default function ExternalLinks() {
  return (
    <div>
      <OutboundLink href="https://example.com">
        Visit Example Site
      </OutboundLink>
      
      <OutboundLink 
        href="https://docs.example.com" 
        target="_blank"
        rel="noopener noreferrer"
      >
        View Documentation
      </OutboundLink>
    </div>
  );
}

With Custom Click Handler

import React from "react";
import { OutboundLink } from "gatsby-plugin-google-gtag";

export default function TrackedLinks() {
  const handleLinkClick = (event) => {
    console.log("Custom click logic before tracking");
    // Custom logic here - gtag tracking happens automatically after
  };

  return (
    <OutboundLink
      href="https://partner-site.com"
      onClick={handleLinkClick}
    >
      Partner Site
    </OutboundLink>
  );
}

With Ref Forwarding

import React, { useRef } from "react";
import { OutboundLink } from "gatsby-plugin-google-gtag";

export default function RefExample() {
  const linkRef = useRef(null);

  const focusLink = () => {
    linkRef.current?.focus();
  };

  return (
    <div>
      <OutboundLink 
        ref={linkRef}
        href="https://example.com"
      >
        External Link
      </OutboundLink>
      <button onClick={focusLink}>Focus Link</button>
    </div>
  );
}

Component Behavior

Automatic Event Tracking

The OutboundLink component automatically fires a gtag event when clicked:

window.gtag("event", "click", {
  event_category: "outbound",
  event_label: href, // The target URL
  transport_type: redirect ? "beacon" : "",
  event_callback: function () {
    if (redirect) {
      document.location = href;
    }
  },
});

Smart Navigation Handling

The component intelligently handles navigation based on user behavior:

  • Normal clicks: Prevents default navigation, fires gtag event, then navigates
  • Modified clicks: Allows default behavior for Ctrl+click, Cmd+click, Alt+click, Shift+click
  • New tab/window: Allows default behavior when target is not _self
  • Prevented events: Respects preventDefault() from custom click handlers

Fallback Behavior

  • If gtag is not available, navigation proceeds normally
  • If gtag event fails, navigation still occurs via fallback
  • Uses beacon transport for reliable event delivery before navigation

PropTypes Validation

The component validates props during development:

OutboundLink.propTypes = {
  href: PropTypes.string,
  target: PropTypes.string,
  onClick: PropTypes.func,
};

All Standard Anchor Props

OutboundLink accepts all standard HTML anchor element props:

  • href, target, rel, download
  • className, style, id
  • aria-* attributes for accessibility
  • Event handlers: onMouseOver, onFocus, etc.
  • Any other valid anchor attributes

The component forwards all props to the underlying <a> element while adding tracking behavior.