API reference

`useContent()`

The useContent() function retrieves the nearest content information for the current route. The returned object includes:

headings: ContentHeading[] | undefined;
menu: ContentMenu | undefined;

The headings array includes data about a markdown file's <h1> to <h6> html heading elements.

Menus are contextual data declared with menu.md files. See menus file definition for more information on the file format and location.

`useDocumentHead()`

Use the useDocumentHead() function to retrieve the document head metadata.

useDocumentHead() retrieves a DocumentHead object that will allow you to:

update the title in <head>.
update the meta tags in <head>.
update the link tags in <head>.
update the style tags in <head>.

The useDocumentHead() function can be used within a Qwik component, such as <Head>, to create the inner elements within document.head.

`useLocation()`

Use the useLocation() function to retrieve a RouteLocation object for the current location.

export interface RouteLocation {
  readonly params: RouteParams; // Record<string,string>
  readonly href: string;
  readonly pathname: string;
  readonly query: Record<string, string>;
}

The return value of useLocation() is similar to document.location, but it is safe to use on the server where there is no global location object.

Path Route Parameters

useLocation() encodes the Route Parameters as params.

Assume you have:

Route: https://example.com/sku/[skuId]
User navigates to: https://example.com/sku/1234
Then the skuId can be retrieved through useLocation().params.skuId.

import { component$ } from '@builder.io/qwik';
import { useLocation } from '@builder.io/qwik-city';

export default component$(() => {
  const loc = useLocation();

  return (
    <>
      <h1>SKU</h1>
      <p>pathname: {loc.pathname}</p>
      <p>skuId: {loc.params.skuId}</p>
    </>
  );
});

The above code would generate:

<h1>SKU</h1>
<p>pathname: /sku/1234</p>
<p>skuId: 1234</p>

Notice that useLocation is a read-only API, you should never attempt to mutate the values of the loc object returned. Instead look into the useNavigate() API.

`useNavigate()`

The useNavigate() function allows to programatically navigate to the next page without involving a user click or causing a full-page reload. This is the API used by the <Link> component internally to support SPA navigation.

While it looks a lot like useLocation, this API is write-only, you should never read the value, instead you can use it to write where you wanna navigate first.

import { component$ } from '@builder.io/qwik';
import { useNavigate } from '@builder.io/qwik-city';

export default component$(() => {
  const nav = useNavigate();

  return (
    <>
      <button
        onClick$={() => {
          // this assigment causes SPA navigation
          nav.path = '/dashboard';
        }}
      >
        Go to dashboard
      </button>
    </>
  );
});

This component will have a button then when clicked, QwikCity will navigate to /dashboard without causing a page reload.

`useEndpoint()`

This is the main API to retrieve data from the server! It works like a RPC, calling the server and returning a resource, that will resolve to the actual data.

Please look at the Data fetching docs for more details, specifically the retrieve section.

import { Resource, component$, useStore } from '@builder.io/qwik';
import type { RequestHandler } from '@builder.io/qwik-city';
import { useEndpoint } from '@builder.io/qwik-city';

export const onGet: RequestHandler<number> = async ({ params }) => {
  // This code runs in the Server
  const PI = computePIinServer();
  return PI;
};

export default component$(() => {
  const piResource = useEndpoint<number>();
  return (
    <Resource
      value={piResource}
      onResolved={(pi) => (
        <>
          <p>Number PI is: {pi}</p>
        </>
      )}
    />
  );
});

Resulting in the following HTML:

<p>Number PI is: 3.14159</p>

useEndpoint() abstracts away the need to run logic in the server and retrieve this data in the client, in a way that is SSR friendly!

`<QwikCityProvider>`

The QwikCityProvider component initializes QwikCity in the existing document, providing the necessary context for QwikCity to work, such as useContent() and useLocation().

This component is usually located at the very root of your application, in most of the starters you will find it in the src/root.tsx file:

import { QwikCityProvider, RouterOutlet } from '@builder.io/qwik-city';

export default function Root() {
  return (
    <QwikCityProvider>
      <head>
        <meta charSet="utf-8" />
      </head>
      <body>
        <RouterOutlet />
      </body>
    </QwikCityProvider>
  );
}

QwikCityProvider does not render any DOM element, not even the matched route, it merely initializes QwikCity core logic, because of this reason, it should not be used more than once in the same app.

`<RouterOutlet>`

This component is the responsable for rendering the matched route at a given moment, it used internally the useContent() and to render the current page, as well as all the nested layouts.

This component is usually located as a child of <body>, in most of the starters you will find it in the src/root.tsx file:

`<Link>`

The Link component works like the <a> anchor element, but instead of causing a full page reload, it will navigate as a SPA (Single Page Navigation). This is useful if you need to navigate without losing current state.

Notice that full-page reloads in Qwik are extremely cheap, other frameworks abuse SPA links because, a full page reload requires JS to hydrate and reexecute everything. This is not the case for Qwik. We found in our internal testing that using <a> usually leads to the most snappy interactions.

Under the hood, the <Link> component uses the useNavigate() API and prevents the default behaviour of the native <a>:

export const Link = component$<LinkProps>((props) => {
  const nav = useNavigate();

  return (
    <a
      preventdefault:click
      onClick$={() => {
        nav(props.href);
      }}
      {...props}
    >
      <Slot />
    </a>
  );
});

Usage

import { component$ } from '@builder.io/qwik';
import { Link } from '@builder.io/qwik-city';

export default component$(() => {
  return (
    <div>
      <a href="/docs" class="my-link">
        full-page reload
      </a>
      <Link href="/docs" class="my-link">
        spa navigation
      </Link>
    </div>
  );
});