feat(link): accept external URLs in Link to prop (#4901)

packages/router-core/src/index.ts

@@ -30,6 +30,7 @@ export type {
   SearchParamOptions,
   PathParamOptions,
   ToPathOption,
+  ExternalUrl,
   LinkOptions,
   MakeOptionalPathParams,
   FromPathOption,

packages/router-core/src/link.ts

@@ -613,18 +613,39 @@ export type PathParamOptions<TRouter extends AnyRouter, TFrom, TTo> =
     ? MakeOptionalPathParams<TRouter, TFrom, TTo>
     : MakeRequiredPathParams<TRouter, TFrom, TTo>
 
+/**
+ * Absolute external URL strings accepted by the `to` prop on `Link`,
+ * `createLink`, and `linkOptions`. Matches the runtime `new URL(to)` check in
+ * `useLinkProps` and the default protocol allowlist (`http:`, `https:`,
+ * `mailto:`, `tel:`). When `to` matches one of these patterns the runtime
+ * short-circuits internal-route handling and renders the value as an
+ * anchor's `href` (still applying `isDangerousProtocol` filtering).
+ *
+ * Internal route paths (e.g. `/dashboard`, `../profile`) remain valid; this
+ * type only widens what is accepted, never narrows it.
+ *
+ * @see https://github.com/TanStack/router/issues/4901
+ */
+export type ExternalUrl =
+  | `http://${string}`
+  | `https://${string}`
+  | `mailto:${string}`
+  | `tel:${string}`
+
 export type ToPathOption<
   TRouter extends AnyRouter = AnyRouter,
   TFrom extends string = string,
   TTo extends string | undefined = string,
-> = ConstrainLiteral<
-  TTo,
-  RelativeToPathAutoComplete<
-    TRouter,
-    NoInfer<TFrom> extends string ? NoInfer<TFrom> : '',
-    NoInfer<TTo> & string
-  >
->
+> =
+  | ConstrainLiteral<
+      TTo,
+      RelativeToPathAutoComplete<
+        TRouter,
+        NoInfer<TFrom> extends string ? NoInfer<TFrom> : '',
+        NoInfer<TTo> & string
+      >
+    >
+  | ExternalUrl
 
 export type FromPathOption<TRouter extends AnyRouter, TFrom> = ConstrainLiteral<
   TFrom,

packages/router-core/tests/external-url.test-d.ts

@@ -0,0 +1,45 @@
+import { describe, expectTypeOf, test } from 'vitest'
+import type { ExternalUrl, ToPathOption } from '../src/link'
+
+// Regression coverage for https://github.com/TanStack/router/issues/4901.
+// `to` on `Link`/`createLink`/`linkOptions` should accept absolute external
+// URLs (https, mailto, tel, http) in addition to internal route paths.
+describe('ExternalUrl', () => {
+  test('matches https URLs', () => {
+    expectTypeOf<'https://example.com'>().toMatchTypeOf<ExternalUrl>()
+    expectTypeOf<'https://example.com/path?query=1#hash'>().toMatchTypeOf<ExternalUrl>()
+  })
+
+  test('matches http URLs', () => {
+    expectTypeOf<'http://example.com'>().toMatchTypeOf<ExternalUrl>()
+  })
+
+  test('matches mailto: URLs', () => {
+    expectTypeOf<'mailto:user@example.com'>().toMatchTypeOf<ExternalUrl>()
+  })
+
+  test('matches tel: URLs', () => {
+    expectTypeOf<'tel:+15551234567'>().toMatchTypeOf<ExternalUrl>()
+  })
+
+  test('rejects internal route paths (no scheme)', () => {
+    // Without a scheme these are NOT external URLs.
+    expectTypeOf<'/dashboard'>().not.toMatchTypeOf<ExternalUrl>()
+    expectTypeOf<'../profile'>().not.toMatchTypeOf<ExternalUrl>()
+  })
+})
+
+describe('ToPathOption', () => {
+  test('accepts absolute external URLs', () => {
+    // Default generics: no specific router/type constraints.
+    // `to` should now accept any ExternalUrl.
+    expectTypeOf<'https://example.com'>().toMatchTypeOf<ToPathOption>()
+    expectTypeOf<'mailto:user@example.com'>().toMatchTypeOf<ToPathOption>()
+    expectTypeOf<'tel:+15551234567'>().toMatchTypeOf<ToPathOption>()
+  })
+
+  test('still accepts internal route paths', () => {
+    // Backward compat: internal paths must remain assignable to `to`.
+    expectTypeOf<string>().toMatchTypeOf<ToPathOption>()
+  })
+})