# gatsby-plugin-catch-links

> Intercepts local links from markdown and other non-react pages and does a client-side pushState to avoid the browser having to refresh the page.

Latest version **5.16.0** (published 2026-01-26) · MIT license · 0 weekly downloads

## Install

```sh
npm install gatsby-plugin-catch-links
pnpm add gatsby-plugin-catch-links
yarn add gatsby-plugin-catch-links
bun add gatsby-plugin-catch-links
```

## Health

**Score 60/100 (C)** — status: stable.

Positive: no vulnerabilities; high maintenance score; popular repo; extremely popular.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 5.16.0 |
| Published | 2026-01-26 |
| First published | 2017-02-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=18.0.0 <26 |
| Dependencies | 2 |
| Unpacked size | 52.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 55938 |
| Author | Kyle Mathews |
| Maintainers | pieh, kathmbeck, serhalp-netlify, mlgualtieri-gatsby, fk, tylerbarnes, daniellewgatsby |
| Keywords | gatsby, gatsby-plugin |

## Links

- npm: https://www.npmjs.com/package/gatsby-plugin-catch-links
- Repository: https://github.com/gatsbyjs/gatsby
- Homepage: https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-catch-links#readme
- Issues: https://github.com/gatsbyjs/gatsby/issues
- npm.io page: https://npm.io/package/gatsby-plugin-catch-links

## Dependencies (2)

- [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.20.13
- [escape-string-regexp](https://npm.io/package/escape-string-regexp.md) ^1.0.5

## Recent versions

- 5.16.0 (latest) — 2026-01-26
- 5.17.0-next.0 (next) — 2025-11-27
- 5.17.0-react19.1 (react19) — 2025-11-26
- 3.15.0 (latest-v3) — 2022-12-07
- 4.25.0 (latest-v4) — 2022-12-07
- 5.0.0-alpha-drupal-proxyurl.14 (drupal-proxyurl) — 2022-11-22
- 4.14.0-alpha-transformer-json.26 (alpha-transformer-json) — 2022-10-12
- 5.0.0-alpha-v5.d20221012t101120.57 (alpha-v5) — 2022-10-12
- 4.23.0-alpha-a5-peer.70 (alpha-a5-peer) — 2022-09-14
- 4.23.0-alpha-preview-gh-api.26 (preview-gh-api) — 2022-09-08
- 4.23.0-alpha-9689ff.25 (alpha-9689ff) — 2022-08-31
- 4.18.0-alpha-drupal-self-reference.18 (drupal-self-reference) — 2022-07-19
- 4.15.0-alpha-wp-image-cdn-auth.48 (wp-image-cdn-auth) — 2022-05-20
- 4.8.0-alpha-image-service.24 (image-service) — 2022-02-10
- 4.6.0-alpha-ts-jit.60 (alpha-ts-jit) — 2022-01-21
- … 509 more at https://npm.io/package/gatsby-plugin-catch-links/versions

## README

# gatsby-plugin-catch-links

This plugin intercepts all local links that have not been created in React using [`gatsby-link`](https://gatsbyjs.com/docs/gatsby-link), and replaces their behavior with that of the `gatsby-link` [`navigate`](https://gatsbyjs.com/docs/gatsby-link/#how-to-use-the-navigate-helper-function). This avoids the browser having to refresh the whole page when navigating between local pages, preserving the Single Page Application (SPA) feel.

Example use cases:

- A markdown file with relative links (transformed
  to `a` tags by
  [`gatsby-transformer-remark`](/plugins/gatsby-transformer-remark/))
- An `a` tag that has been created by a Content Management System (CMS) WYSIWYG editor

## Installation

```shell
npm install gatsby-plugin-catch-links
```

## How to use

```javascript
// In your gatsby-config.js
plugins: [`gatsby-plugin-catch-links`]
```

## Plugin Options

**`excludePattern`** [Regular Expression][optional]

Regular expression for paths to be excluded from being handled by this plugin.

```javascript
{
  resolve: `gatsby-plugin-catch-links`,
  options: {
    excludePattern: /(excluded-link|external)/,
  },
},
```

## Examples

- Check out this live example [_Using Remark_](https://using-remark.gatsbyjs.org/copy-linked-files-intercepting-local-links/#intercepting-local-links) to see this plugin in action. The full source code for this example can be found [here](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-remark).

---
_Source: https://npm.io/package/gatsby-plugin-catch-links · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._