@tanstack/react-router 1.159.14 → 1.160.0

package/dist/llms/rules/api.js

@@ -1553,6 +1553,41 @@ The \`RouterOptions\` type accepts an object with the following properties and m
 - When \`true\`, disables the global catch boundary that normally wraps all route matches. This allows unhandled errors to bubble up to top-level error handlers in the browser.
 - Useful for testing tools, error reporting services, and debugging scenarios.
 
+### \`protocolAllowlist\` property
+
+- Type: \`Array<string>\`
+- Optional
+- Defaults to \`DEFAULT_PROTOCOL_ALLOWLIST\` which includes:
+  - Web navigation: \`http:\`, \`https:\`
+  - Common browser-safe actions: \`mailto:\`, \`tel:\`
+- An array of URL protocols that are allowed in links, redirects, and navigation. Absolute URLs with protocols not in this list are rejected to prevent security vulnerabilities like XSS attacks.
+- This check is applied across router navigation APIs, including:
+  - \`<Link to="...">\`
+  - \`navigate({ to: ... })\` and \`navigate({ href: ... })\`
+  - \`redirect({ to: ... })\` and \`redirect({ href: ... })\`
+- Protocol entries must match \`URL.protocol\` format (lowercase with a trailing \`:\`), for example \`blob:\` or \`data:\`. If you configure \`protocolAllowlist: ['blob']\` (without \`:\`), links using \`blob:\` will still be blocked.
+
+**Example**
+
+\`\`\`tsx
+import {
+  createRouter,
+  DEFAULT_PROTOCOL_ALLOWLIST,
+} from '@tanstack/react-router'
+
+// Use a custom allowlist (replaces the default)
+const router = createRouter({
+  routeTree,
+  protocolAllowlist: ['https:', 'mailto:'],
+})
+
+// Or extend the default allowlist
+const router = createRouter({
+  routeTree,
+  protocolAllowlist: [...DEFAULT_PROTOCOL_ALLOWLIST, 'ftp:'],
+})
+\`\`\`
+
 ### \`defaultViewTransition\` property
 
 - Type: \`boolean | ViewTransitionOptions\`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/react-router",
-  "version": "1.159.14",
+  "version": "1.160.0",
   "description": "Modern and scalable routing for React applications",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -82,7 +82,7 @@
     "tiny-invariant": "^1.3.3",
     "tiny-warning": "^1.0.3",
     "@tanstack/history": "1.154.14",
-    "@tanstack/router-core": "1.159.9"
+    "@tanstack/router-core": "1.160.0"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.6.3",

package/src/index.tsx

@@ -243,7 +243,12 @@ export { useMatch } from './useMatch'
 export { useLoaderDeps } from './useLoaderDeps'
 export { useLoaderData } from './useLoaderData'
 
-export { redirect, isRedirect, createRouterConfig } from '@tanstack/router-core'
+export {
+  redirect,
+  isRedirect,
+  createRouterConfig,
+  DEFAULT_PROTOCOL_ALLOWLIST,
+} from '@tanstack/router-core'
 
 export {
   RouteApi,

package/src/link.tsx

@@ -118,7 +118,7 @@ export function useLinkProps<
     ) {
       try {
         new URL(to)
-        if (isDangerousProtocol(to)) {
+        if (isDangerousProtocol(to, router.protocolAllowlist)) {
           if (process.env.NODE_ENV !== 'production') {
             console.warn(`Blocked Link with dangerous protocol: ${to}`)
           }
@@ -170,7 +170,7 @@ export function useLinkProps<
 
     const externalLink = (() => {
       if (hrefOption?.external) {
-        if (isDangerousProtocol(hrefOption.href)) {
+        if (isDangerousProtocol(hrefOption.href, router.protocolAllowlist)) {
           if (process.env.NODE_ENV !== 'production') {
             console.warn(
               `Blocked Link with dangerous protocol: ${hrefOption.href}`,
@@ -187,7 +187,7 @@ export function useLinkProps<
       if (typeof to === 'string' && to.indexOf(':') > -1) {
         try {
           new URL(to)
-          if (isDangerousProtocol(to)) {
+          if (isDangerousProtocol(to, router.protocolAllowlist)) {
             if (process.env.NODE_ENV !== 'production') {
               console.warn(`Blocked Link with dangerous protocol: ${to}`)
             }
@@ -438,7 +438,7 @@ export function useLinkProps<
   const externalLink = React.useMemo(() => {
     if (hrefOption?.external) {
       // Block dangerous protocols for external links
-      if (isDangerousProtocol(hrefOption.href)) {
+      if (isDangerousProtocol(hrefOption.href, router.protocolAllowlist)) {
         if (process.env.NODE_ENV !== 'production') {
           console.warn(
             `Blocked Link with dangerous protocol: ${hrefOption.href}`,
@@ -453,8 +453,8 @@ export function useLinkProps<
     if (typeof to !== 'string' || to.indexOf(':') === -1) return undefined
     try {
       new URL(to as any)
-      // Block dangerous protocols like javascript:, data:, vbscript:
-      if (isDangerousProtocol(to)) {
+      // Block dangerous protocols like javascript:, blob:, data:
+      if (isDangerousProtocol(to, router.protocolAllowlist)) {
         if (process.env.NODE_ENV !== 'production') {
           console.warn(`Blocked Link with dangerous protocol: ${to}`)
         }
@@ -463,7 +463,7 @@ export function useLinkProps<
       return to
     } catch {}
     return undefined
-  }, [to, hrefOption])
+  }, [to, hrefOption, router.protocolAllowlist])
 
   // eslint-disable-next-line react-hooks/rules-of-hooks
   const isActive = useRouterState({