QwikDev · wmertens · Aug 4, 2025 · Aug 4, 2025
@@ -0,0 +1,5 @@
+---
+'@qwik.dev/router': minor
+---
+
+FEAT: useQwikRouter() hook replaces QwikRouterProvider. This gives access to the context immediately and is slightly more efficient.
@@ -1,24 +1,24 @@
 import { component$ } from '@qwik.dev/core';
-import { QwikRouterProvider, RouterOutlet } from '@qwik.dev/router';
-import { RouterHead } from './components/router-head/router-head';
+import { DocumentHeadTags, RouterOutlet, useLocation, useQwikRouter } from '@qwik.dev/router';
 
 export default component$(() => {
-  /**
-   * The root of a QwikCity site always start with the <QwikCityProvider> component, immediately
-   * followed by the document's <head> and <body>.
-   *
-   * Don't remove the `<head>` and `<body>` elements.
-   */
+  useQwikRouter();
+
+  const loc = useLocation();
 
   return (
-    <QwikRouterProvider>
+    <>
       <head>
         <meta charset="utf-8" />
-        <RouterHead />
+
+        <DocumentHeadTags />
+
+        <link rel="canonical" href={loc.url.href} />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
       </head>
-      <body lang="en">
+      <body>
         <RouterOutlet />
       </body>
-    </QwikRouterProvider>
+    </>
   );
 });
@@ -1,11 +1,19 @@
 import { component$, useContextProvider, useStore } from '@qwik.dev/core';
 import { Insights } from '@qwik.dev/core/insights';
-import { QwikRouterProvider, RouterOutlet, ServiceWorkerRegister } from '@qwik.dev/router';
+import {
+  RouterOutlet,
+  ServiceWorkerRegister,
+  useDocumentHead,
+  useLocation,
+  useQwikRouter,
+} from '@qwik.dev/router';
 import RealMetricsOptimization from './components/real-metrics-optimization/real-metrics-optimization';
-import { RouterHead } from './components/router-head/router-head';
 import { BUILDER_PUBLIC_API_KEY } from './constants';
 import { GlobalStore, type SiteStore } from './context';
 import './global.css';
+import { ThemeScript } from './components/router-head/theme-script';
+import { Social } from './components/router-head/social';
+import { Vendor } from './components/router-head/vendor';
 
 export const uwu = /*javascript*/ `
 ;(function () {
@@ -41,19 +49,105 @@ export const uwu = /*javascript*/ `
 `;
 
 export default component$(() => {
+  useQwikRouter();
+  const head = useDocumentHead();
+  const { url } = useLocation();
+
   const store = useStore<SiteStore>({
     headerMenuOpen: false,
     sideMenuOpen: false,
   });
 
   useContextProvider(GlobalStore, store);
 
+  const title = head.title
+    ? `${head.title} 📚 Qwik Documentation`
+    : `Qwik - Framework reimagined for the edge`;
+  const description =
+    head.meta.find((m) => m.name === 'description')?.content ||
+    `No hydration, auto lazy-loading, edge-optimized, and fun 🎉!`;
+
+  const OGImage = {
+    imageURL: '',
+    ogImgTitle: '',
+    ogImgSubTitle: '' as string | undefined,
+
+    get URL() {
+      //turn the title into array with [0] -> Title [1] -> subTitle
+      const arrayedTitle = title.split(' | ');
+      const ogImageUrl = new URL('https://opengraphqwik.vercel.app/api/og?level=1');
+
+      // biggerTitle
+      this.ogImgTitle = arrayedTitle[0];
+      //smallerTitle
+      this.ogImgSubTitle = arrayedTitle[1]
+        ? arrayedTitle[1].replace(' 📚 Qwik Documentation', '')
+        : undefined;
+
+      //decide whether or not to show dynamic OGimage or use docs default social card
+      if (this.ogImgSubTitle == undefined || this.ogImgTitle == undefined) {
+        this.imageURL = new URL(`/logos/social-card.jpg`, url).href;
+
+        return this.imageURL;
+      } else {
+        ogImageUrl.searchParams.set('title', this.ogImgTitle);
+        ogImageUrl.searchParams.set('subtitle', this.ogImgSubTitle);
+        // ogImageUrl.searchParams.set('level', this.routeLevel.toString());
+
+        this.imageURL = ogImageUrl.toString();
+
+        return this.imageURL;
+      }
+    },
+  };
+
   return (
-    <QwikRouterProvider>
+    <>
       <head>
         <meta charset="utf-8" />
+
+        <title>{title}</title>
+        <meta name="description" content={description} />
+        <link rel="canonical" href={head.frontmatter?.canonical || url.href} />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <meta name="apple-mobile-web-app-title" content="Qwik" />
+        <meta name="application-name" content="Qwik" />
+        <meta name="apple-mobile-web-app-title" content="Qwik" />
+        <meta name="theme-color" content="#006ce9" />
+        <meta name="color-scheme" content="dark light" />
+
+        <link rel="apple-touch-icon" sizes="180x180" href="/favicons/apple-touch-icon.png" />
+        <link rel="icon" href="/favicons/favicon.svg" type="image/svg+xml" />
+
+        {import.meta.env.PROD && (
+          <>
+            <Social title={title} description={description} href={url.href} ogImage={OGImage.URL} />
+            <Vendor />
+          </>
+        )}
+
+        {/* The below are tags that were collected from all the `head` exports in the current route. */}
+        {head.meta
+          // Skip description because that was already added at the top
+          .filter((s) => s.name !== 'description')
+          .map((m, key) => (
+            <meta key={key} {...m} />
+          ))}
+
+        {head.links.map((l, key) => (
+          <link key={key} {...l} />
+        ))}
+
+        {head.styles.map((s, key) => (
+          <style key={key} {...s.props} dangerouslySetInnerHTML={s.style} />
+        ))}
+
+        {head.scripts.map((s, key) => (
+          <script key={key} {...s.props} dangerouslySetInnerHTML={s.script} />
+        ))}
+
+        <ThemeScript />
         <script dangerouslySetInnerHTML={uwu} />
-        <RouterHead />
 
         <ServiceWorkerRegister />
 
@@ -66,10 +160,11 @@ export default component$(() => {
           'menu-open': store.sideMenuOpen,
         }}
       >
+        {/* This renders the current route, including all Layout components. */}
         <RouterOutlet />
         <RealMetricsOptimization builderApiKey={BUILDER_PUBLIC_API_KEY} />
       </body>
-    </QwikRouterProvider>
+    </>
   );
 });
 

@@ -600,7 +600,7 @@
         }
       ],
       "kind": "Variable",
-      "content": "> Warning: This API is now obsolete.\n> \n> Use `QwikRouterMockProvider` instead. Will be removed in V3\n> \n\n\n```typescript\nQwikCityMockProvider: import(\"@qwik.dev/core\").Component<QwikRouterMockProps>\n```",
+      "content": "> Warning: This API is now obsolete.\n> \n> Use `useQwikMockRouter()` instead. Will be removed in V3\n> \n\n\n```typescript\nQwikCityMockProvider: import(\"@qwik.dev/core\").Component<QwikRouterMockProps>\n```",
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/runtime/src/qwik-router-component.tsx",
       "mdFile": "router.qwikcitymockprovider.md"
     },
@@ -628,7 +628,7 @@
         }
       ],
       "kind": "TypeAlias",
-      "content": "> Warning: This API is now obsolete.\n> \n> Use `QwikRouterProps` instead. will be removed in V3\n> \n\n\n```typescript\nexport type QwikCityProps = QwikRouterProps;\n```\n**References:** [QwikRouterProps](#qwikrouterprops)",
+      "content": "> Warning: This API is now obsolete.\n> \n> Use `QwikRouterProps` instead. Will be removed in v3.\n> \n\n\n```typescript\nexport type QwikCityProps = QwikRouterProps;\n```\n**References:** [QwikRouterProps](#qwikrouterprops)",
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/runtime/src/qwik-router-component.tsx",
       "mdFile": "router.qwikcityprops.md"
     },
@@ -642,7 +642,7 @@
         }
       ],
       "kind": "Variable",
-      "content": "> Warning: This API is now obsolete.\n> \n> Use `QwikRouterProvider` instead. will be removed in V3\n> \n\n\n```typescript\nQwikCityProvider: import(\"@qwik.dev/core\").Component<QwikRouterProps>\n```",
+      "content": "> Warning: This API is now obsolete.\n> \n> Use `useQwikRouter()` instead. Will be removed in v3.\n> \n\n\n```typescript\nQwikCityProvider: import(\"@qwik.dev/core\").Component<QwikRouterProps>\n```",
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/runtime/src/qwik-router-component.tsx",
       "mdFile": "router.qwikcityprovider.md"
     },
@@ -726,7 +726,7 @@
         }
       ],
       "kind": "Variable",
-      "content": "```typescript\nQwikRouterProvider: import(\"@qwik.dev/core\").Component<QwikRouterProps>\n```",
+      "content": "This is a wrapper around the `useQwikRouter()` hook. We recommend using the hook instead of this component.\n\n\n```typescript\nQwikRouterProvider: import(\"@qwik.dev/core\").Component<QwikRouterProps>\n```",
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/runtime/src/qwik-router-component.tsx",
       "mdFile": "router.qwikrouterprovider.md"
     },
@@ -1066,6 +1066,20 @@
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/runtime/src/use-functions.ts",
       "mdFile": "router.usepreventnavigate_.md"
     },
+    {
+      "name": "useQwikRouter",
+      "id": "useqwikrouter",
+      "hierarchy": [
+        {
+          "name": "useQwikRouter",
+          "id": "useqwikrouter"
+        }
+      ],
+      "kind": "Function",
+      "content": "This hook initializes Qwik Router, providing the necessary context for it to work.\n\nThis hook should be used once, at the root of your application.\n\n\n```typescript\nuseQwikRouter: (props?: QwikRouterProps) => void\n```\n\n\n<table><thead><tr><th>\n\nParameter\n\n\n</th><th>\n\nType\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\nprops\n\n\n</td><td>\n\n[QwikRouterProps](#qwikrouterprops)\n\n\n</td><td>\n\n_(Optional)_\n\n\n</td></tr>\n</tbody></table>\n**Returns:**\n\nvoid",
+      "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/runtime/src/qwik-router-component.tsx",
+      "mdFile": "router.useqwikrouter.md"
+    },
     {
       "name": "valibot$",
       "id": "valibot_",

@@ -1400,7 +1400,7 @@ export type QwikCityMockProps = QwikRouterMockProps;
 
 > Warning: This API is now obsolete.
 >
-> Use `QwikRouterMockProvider` instead. Will be removed in V3
+> Use `useQwikMockRouter()` instead. Will be removed in V3
 
 ```typescript
 QwikCityMockProvider: import("@qwik.dev/core").Component<QwikRouterMockProps>;
@@ -1426,7 +1426,7 @@ export type QwikCityPlan = QwikRouterConfig;
 
 > Warning: This API is now obsolete.
 >
-> Use `QwikRouterProps` instead. will be removed in V3
+> Use `QwikRouterProps` instead. Will be removed in v3.
 
 ```typescript
 export type QwikCityProps = QwikRouterProps;
@@ -1440,7 +1440,7 @@ export type QwikCityProps = QwikRouterProps;
 
 > Warning: This API is now obsolete.
 >
-> Use `QwikRouterProvider` instead. will be removed in V3
+> Use `useQwikRouter()` instead. Will be removed in v3.
 
 ```typescript
 QwikCityProvider: import("@qwik.dev/core").Component<QwikRouterProps>;
@@ -1793,6 +1793,8 @@ Default: `true`
 
 ## QwikRouterProvider
 
+This is a wrapper around the `useQwikRouter()` hook. We recommend using the hook instead of this component.
+
 ```typescript
 QwikRouterProvider: import("@qwik.dev/core").Component<QwikRouterProps>;
 ```
@@ -2375,6 +2377,49 @@ void
 
 [Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/runtime/src/use-functions.ts)
 
+## useQwikRouter
+
+This hook initializes Qwik Router, providing the necessary context for it to work.
+
+This hook should be used once, at the root of your application.
+
+```typescript
+useQwikRouter: (props?: QwikRouterProps) => void
+```
+
+<table><thead><tr><th>
+
+Parameter
+
+</th><th>
+
+Type
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody><tr><td>
+
+props
+
+</td><td>
+
+[QwikRouterProps](#qwikrouterprops)
+
+</td><td>
+
+_(Optional)_
+
+</td></tr>
+</tbody></table>
+**Returns:**
+
+void
+
+[Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/runtime/src/qwik-router-component.tsx)
+
 ## valibot$
 
 > This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.