API → @builder.io/qwik-city

Action

export type Action<
  RETURN,
  INPUT = Record<string, unknown>,
  OPTIONAL extends boolean = true,
> = {
  (): ActionStore<RETURN, INPUT, OPTIONAL>;
};

References: ActionStore

Edit this section

ActionConstructor

export type ActionConstructor = {
  <
    OBJ extends Record<string, any> | void | null,
    VALIDATOR extends TypedDataValidator,
    REST extends [DataValidator, ...DataValidator[]],
  >(
    actionQrl: (
      data: GetValidatorOutputType<VALIDATOR>,
      event: RequestEventAction,
    ) => ValueOrPromise<OBJ>,
    options: {
      readonly id?: string;
      readonly validation: [VALIDATOR, ...REST];
    },
  ): Action<
    StrictUnion<
      | OBJ
      | FailReturn<ValidatorErrorType<GetValidatorInputType<VALIDATOR>>>
      | FailReturn<FailOfRest<REST>>
    >,
    GetValidatorInputType<VALIDATOR>,
    false
  >;
  <
    OBJ extends Record<string, any> | void | null,
    VALIDATOR extends TypedDataValidator,
  >(
    actionQrl: (
      data: GetValidatorOutputType<VALIDATOR>,
      event: RequestEventAction,
    ) => ValueOrPromise<OBJ>,
    options: {
      readonly id?: string;
      readonly validation: [VALIDATOR];
    },
  ): Action<
    StrictUnion<
      OBJ | FailReturn<ValidatorErrorType<GetValidatorInputType<VALIDATOR>>>
    >,
    GetValidatorInputType<VALIDATOR>,
    false
  >;
  <
    OBJ extends Record<string, any> | void | null,
    REST extends [DataValidator, ...DataValidator[]],
  >(
    actionQrl: (
      data: JSONObject,
      event: RequestEventAction,
    ) => ValueOrPromise<OBJ>,
    options: {
      readonly id?: string;
      readonly validation: REST;
    },
  ): Action<StrictUnion<OBJ | FailReturn<FailOfRest<REST>>>>;
  <
    OBJ extends Record<string, any> | void | null,
    VALIDATOR extends TypedDataValidator,
    REST extends [DataValidator, ...DataValidator[]],
  >(
    actionQrl: (
      data: GetValidatorOutputType<VALIDATOR>,
      event: RequestEventAction,
    ) => ValueOrPromise<OBJ>,
    options: VALIDATOR,
    ...rest: REST
  ): Action<
    StrictUnion<
      | OBJ
      | FailReturn<ValidatorErrorType<GetValidatorInputType<VALIDATOR>>>
      | FailReturn<FailOfRest<REST>>
    >,
    GetValidatorInputType<VALIDATOR>,
    false
  >;
  <
    OBJ extends Record<string, any> | void | null,
    VALIDATOR extends TypedDataValidator,
  >(
    actionQrl: (
      data: GetValidatorOutputType<VALIDATOR>,
      event: RequestEventAction,
    ) => ValueOrPromise<OBJ>,
    options: VALIDATOR,
  ): Action<
    StrictUnion<
      OBJ | FailReturn<ValidatorErrorType<GetValidatorInputType<VALIDATOR>>>
    >,
    GetValidatorInputType<VALIDATOR>,
    false
  >;
  <
    OBJ extends Record<string, any> | void | null,
    REST extends [DataValidator, ...DataValidator[]],
  >(
    actionQrl: (
      form: JSONObject,
      event: RequestEventAction,
    ) => ValueOrPromise<OBJ>,
    ...rest: REST
  ): Action<StrictUnion<OBJ | FailReturn<FailOfRest<REST>>>>;
  <OBJ>(
    actionQrl: (
      form: JSONObject,
      event: RequestEventAction,
    ) => ValueOrPromise<OBJ>,
    options?: {
      readonly id?: string;
    },
  ): Action<StrictUnion<OBJ>>;
};

References: TypedDataValidator, DataValidator, GetValidatorOutputType, Action, StrictUnion, FailReturn, ValidatorErrorType, GetValidatorInputType, FailOfRest, JSONObject

Edit this section

ActionReturn

export type ActionReturn<RETURN> = {
  readonly status?: number;
  readonly value: RETURN;
};

Edit this section

ActionStore

export type ActionStore<RETURN, INPUT, OPTIONAL extends boolean = true> = {
  readonly actionPath: string;
  readonly isRunning: boolean;
  readonly status?: number;
  readonly formData: FormData | undefined;
  readonly value: RETURN | undefined;
  readonly submit: QRL<
    OPTIONAL extends true
      ? (form?: INPUT | FormData | SubmitEvent) => Promise<ActionReturn<RETURN>>
      : (form: INPUT | FormData | SubmitEvent) => Promise<ActionReturn<RETURN>>
  >;
  readonly submitted: boolean;
};

References: ActionReturn

Edit this section

ContentHeading

export interface ContentHeading

Edit this section

ContentMenu

export interface ContentMenu

Edit this section

DataValidator

export type DataValidator<T extends Record<string, any> = {}> = {
  validate(ev: RequestEvent, data: unknown): Promise<ValidatorReturn<T>>;
};

References: ValidatorReturn

Edit this section

DocumentHead

export type DocumentHead =
  | DocumentHeadValue
  | ((props: DocumentHeadProps) => DocumentHeadValue);

References: DocumentHeadValue, DocumentHeadProps

Edit this section

DocumentHeadProps

export interface DocumentHeadProps extends RouteLocation

Extends: RouteLocation

Edit this section

DocumentHeadValue

export interface DocumentHeadValue<FrontMatter extends Record<string, any> = Record<string, unknown>>

Edit this section

DocumentLink

export interface DocumentLink

Edit this section

DocumentMeta

export interface DocumentMeta

Edit this section

DocumentScript

This API is provided as an alpha preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

export interface DocumentScript

Edit this section

DocumentStyle

export interface DocumentStyle

Edit this section

ErrorBoundary

ErrorBoundary: import("@builder.io/qwik").Component<ErrorBoundaryProps>;

Edit this section

FailOfRest

export type FailOfRest<REST extends readonly DataValidator[]> =
  REST extends readonly DataValidator<infer ERROR>[] ? ERROR : never;

References: DataValidator

Edit this section

FailReturn

export type FailReturn<T> = T & Failed;

Edit this section

Form

Form: <O, I>(
  { action, spaReset, reloadDocument, onSubmit$, ...rest }: FormProps<O, I>,
  key: string | null,
) => import("@builder.io/qwik").JSXOutput;

Returns:

import("@builder.io/qwik").JSXOutput

Edit this section

FormProps

export interface FormProps<O, I> extends Omit<QwikJSX.IntrinsicElements['form'], 'action' | 'method'>

Extends: Omit<QwikJSX.IntrinsicElements['form'], 'action' | 'method'>

Edit this section

FormSubmitSuccessDetail

export interface FormSubmitCompletedDetail<T>

Edit this section

GetValidatorInputType

export type GetValidatorInputType<VALIDATOR extends TypedDataValidator> =
  VALIDATOR extends ValibotDataValidator<infer TYPE>
    ? v.InferInput<TYPE>
    : VALIDATOR extends ZodDataValidator<infer TYPE>
      ? z.input<TYPE>
      : never;

References: TypedDataValidator

Edit this section

GetValidatorOutputType

export type GetValidatorOutputType<VALIDATOR extends TypedDataValidator> =
  VALIDATOR extends ValibotDataValidator<infer TYPE>
    ? v.InferOutput<TYPE>
    : VALIDATOR extends ZodDataValidator<infer TYPE>
      ? z.output<TYPE>
      : never;

References: TypedDataValidator

Edit this section

GetValidatorType

export type GetValidatorType<VALIDATOR extends TypedDataValidator> =
  GetValidatorOutputType<VALIDATOR>;

References: TypedDataValidator, GetValidatorOutputType

Edit this section

globalAction$

globalAction$: ActionConstructor;

Edit this section

globalActionQrl

globalActionQrl: ActionConstructorQRL;

Edit this section

JSONObject

export type JSONObject = {
  [x: string]: JSONValue;
};

References: JSONValue

Edit this section

JSONValue

export type JSONValue =
  | string
  | number
  | boolean
  | {
      [x: string]: JSONValue;
    }
  | Array<JSONValue>;

References: JSONValue

Edit this section

Link

Link: import("@builder.io/qwik").Component<LinkProps>;

Edit this section

LinkProps

export interface LinkProps extends AnchorAttributes

Extends: AnchorAttributes

Edit this section

Loader_2

export type Loader<RETURN> = {
  (): LoaderSignal<RETURN>;
};

References: LoaderSignal

Edit this section

LoaderSignal

export type LoaderSignal<TYPE> = TYPE extends () => ValueOrPromise<
  infer VALIDATOR
>
  ? ReadonlySignal<ValueOrPromise<VALIDATOR>>
  : ReadonlySignal<TYPE>;

Edit this section

MenuData

export type MenuData = [pathname: string, menuLoader: MenuModuleLoader];

Edit this section

NavigationType

export type NavigationType = "initial" | "form" | "link" | "popstate";

Edit this section

PageModule

export interface PageModule extends RouteModule

Extends: RouteModule

Edit this section

PathParams

export declare type PathParams = Record<string, string>;

Edit this section

PreventNavigateCallback

export type PreventNavigateCallback = (
  url?: number | URL,
) => ValueOrPromise<boolean>;

Edit this section

QWIK_CITY_SCROLLER

QWIK_CITY_SCROLLER = "_qCityScroller";

Edit this section

QwikCityMockProps

export interface QwikCityMockProps

Edit this section

QwikCityMockProvider

QwikCityMockProvider: import("@builder.io/qwik").Component<QwikCityMockProps>;

Edit this section

QwikCityPlan

export interface QwikCityPlan

Edit this section

QwikCityProps

export interface QwikCityProps

Edit this section

QwikCityProvider

QwikCityProvider: import("@builder.io/qwik").Component<QwikCityProps>;

Edit this section

ResolvedDocumentHead

export type ResolvedDocumentHead<
  FrontMatter extends Record<string, any> = Record<string, unknown>,
> = Required<DocumentHeadValue<FrontMatter>>;

References: DocumentHeadValue

Edit this section

routeAction$

routeAction$: ActionConstructor;

Edit this section

routeActionQrl

routeActionQrl: ActionConstructorQRL;

Edit this section

RouteData

export type RouteData =
  | [routeName: string, loaders: ModuleLoader[]]
  | [
      routeName: string,
      loaders: ModuleLoader[],
      originalPathname: string,
      routeBundleNames: string[],
    ];

Edit this section

routeLoader$

routeLoader$: LoaderConstructor;

Edit this section

routeLoaderQrl

routeLoaderQrl: LoaderConstructorQRL;

Edit this section

RouteLocation

export interface RouteLocation

Edit this section

RouteNavigate

export type RouteNavigate = QRL<
  (
    path?: string | number | URL,
    options?:
      | {
          type?: Exclude<NavigationType, "initial">;
          forceReload?: boolean;
          replaceState?: boolean;
          scroll?: boolean;
        }
      | boolean,
  ) => Promise<void>
>;

References: NavigationType

Edit this section

RouterOutlet

RouterOutlet: import("@builder.io/qwik").Component<unknown>;

Edit this section

server$

server$: <T extends ServerFunction>(
  qrl: T,
  options?: ServerConfig | undefined,
) => ServerQRL<T>;

Returns:

ServerQRL<T>

Edit this section

ServerFunction

export type ServerFunction = {
  (this: RequestEventBase, ...args: any[]): any;
  options?: ServerConfig;
};

Edit this section

serverQrl

You can pass an AbortSignal as the first argument of a server$ function and it will use it to abort the fetch when fired.

export type ServerQRL<T extends ServerFunction> = QRL<
  | ((abort: AbortSignal, ...args: Parameters<T>) => ReturnType<T>)
  | ((...args: Parameters<T>) => ReturnType<T>)
>;

References: ServerFunction

Edit this section

ServerQRL

You can pass an AbortSignal as the first argument of a server$ function and it will use it to abort the fetch when fired.

export type ServerQRL<T extends ServerFunction> = QRL<
  | ((abort: AbortSignal, ...args: Parameters<T>) => ReturnType<T>)
  | ((...args: Parameters<T>) => ReturnType<T>)
>;

References: ServerFunction

Edit this section

ServiceWorkerRegister

Loads the service workers that are defined in the routes. Any file named service-worker.* (all JS extensions are allowed) will be picked up, bundled into a separate file, and registered as a service worker.

Qwik 1.14.0 and above now use <link rel="modulepreload"> by default. If you didn't add custom service-worker logic, you should remove your service-worker.ts file(s) for the ServiceWorkerRegister Component to actually unregister the service-worker.js and delete its related cache. Make sure to keep the ServiceWorkerRegister Component in your app (without any service-worker.ts file) as long as you want to unregister the service-worker.js for your users.

ServiceWorkerRegister: (props: { nonce?: string }) => JSXOutput;

Returns:

JSXOutput

Edit this section

StaticGenerate

export interface StaticGenerate

Edit this section

StaticGenerateHandler

export type StaticGenerateHandler = ({
  env,
}: {
  env: EnvGetter;
}) => Promise<StaticGenerate> | StaticGenerate;

References: StaticGenerate

Edit this section

StrictUnion

export type StrictUnion<T> = Prettify<StrictUnionHelper<T, T>>;

Edit this section

TypedDataValidator

export type TypedDataValidator = ValibotDataValidator | ZodDataValidator;

Edit this section

useContent

useContent: () => import("./types").ContentState;

Returns:

import("./types").ContentState

Edit this section

useDocumentHead

Returns the document head for the current page. The generic type describes the front matter.

useDocumentHead: <
  FrontMatter extends Record<string, unknown> = Record<string, any>,
>() => Required<ResolvedDocumentHead<FrontMatter>>;

Returns:

Required<ResolvedDocumentHead<FrontMatter>>

Edit this section

useLocation

useLocation: () => RouteLocation;

Returns:

RouteLocation

Edit this section

useNavigate

useNavigate: () => RouteNavigate;

Returns:

RouteNavigate

Edit this section

usePreventNavigate$

Prevent navigation attempts. This hook registers a callback that will be called before SPA or browser navigation.

Return true to prevent navigation.

#### SPA Navigation

For Single-Page-App (SPA) navigation (via <Link />, const nav = useNavigate(), and browser backwards/forwards inside SPA history), the callback will be provided with the target, either a URL or a number. It will only be a number if nav(number) was called to navigate forwards or backwards in SPA history.

If you return a Promise, the navigation will be blocked until the promise resolves.

This can be used to show a nice dialog to the user, and wait for the user to confirm, or to record the url, prevent the navigation, and navigate there later via nav(url).

#### Browser Navigation

However, when the user navigates away by clicking on a regular <a />, reloading, or moving backwards/forwards outside SPA history, this callback will not be awaited. This is because the browser does not provide a way to asynchronously prevent these navigations.

In this case, returning returning true will tell the browser to show a confirmation dialog, which cannot be customized. You are also not able to show your own window.confirm() dialog during the callback, the browser won't allow it. If you return a Promise, it will be considered as true.

When the callback is called from the browser, no url will be provided. Use this to know whether you can show a dialog or just return true to prevent the navigation.

usePreventNavigate$: (qrl: PreventNavigateCallback) => void

Returns:

void

Edit this section

valibot$

This API is provided as an alpha preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

valibot$: ValibotConstructor;

Edit this section

valibotQrl

This API is provided as an alpha preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

valibotQrl: ValibotConstructorQRL;

Edit this section

validator$

validator$: ValidatorConstructor;

Edit this section

ValidatorErrorKeyDotNotation

export type ValidatorErrorKeyDotNotation<T, Prefix extends string = ""> =
  IsAny<T> extends true
    ? never
    : T extends object
      ? {
          [K in keyof T & string]: IsAny<T[K]> extends true
            ? never
            : T[K] extends (infer U)[]
              ? IsAny<U> extends true
                ? never
                : U extends object
                  ?
                      | `${Prefix}${K}[]`
                      | ValidatorErrorKeyDotNotation<U, `${Prefix}${K}[].`>
                  : `${Prefix}${K}[]`
              : T[K] extends object
                ? ValidatorErrorKeyDotNotation<T[K], `${Prefix}${K}.`>
                : `${Prefix}${K}`;
        }[keyof T & string]
      : never;

References: ValidatorErrorKeyDotNotation

Edit this section

ValidatorErrorType

export type ValidatorErrorType<T, U = string> = {
  formErrors: U[];
  fieldErrors: Partial<{
    [K in ValidatorErrorKeyDotNotation<T>]: K extends `${infer _Prefix}[]${infer _Suffix}`
      ? U[]
      : U;
  }>;
};

References: ValidatorErrorKeyDotNotation

Edit this section

validatorQrl

validatorQrl: ValidatorConstructorQRL;

Edit this section

ValidatorReturn

export type ValidatorReturn<T extends Record<string, any> = {}> =
  | ValidatorReturnSuccess
  | ValidatorReturnFail<T>;

Edit this section

zod$

zod$: ZodConstructor;

Edit this section

ZodConstructor

export type ZodConstructor = {
  <T extends z.ZodRawShape>(schema: T): ZodDataValidator<z.ZodObject<T>>;
  <T extends z.ZodRawShape>(
    schema: (zod: typeof z.z, ev: RequestEvent) => T,
  ): ZodDataValidator<z.ZodObject<T>>;
  <T extends z.Schema>(schema: T): ZodDataValidator<T>;
  <T extends z.Schema>(
    schema: (zod: typeof z.z, ev: RequestEvent) => T,
  ): ZodDataValidator<T>;
};

Edit this section

zodQrl

zodQrl: ZodConstructorQRL;

Edit this section

Retrieving Headings with useContent

The useContent hook is a powerful utility in Qwik City that allows you to access the content state of the current page. One of its key features is the ability to retrieve all the headings from .mdx files. This is particularly useful for generating sidebar links or a table of contents for the current page.

Example: Generating Sidebar Links

Here's an example of how you can use useContent to retrieve and display the headings of the current .mdx page:

import { component$, useContent } from '@builder.io/qwik';
 
export const Sidebar = component$(() => {
  const content = useContent();
 
  return (
    <nav>
      <ul>
        {content.headings?.map((heading) => (
          <li key={heading.id}>
            <a href={`#${heading.id}`}>{heading.text}</a>
          </li>
        ))}
      </ul>
    </nav>
  );
});

Notes

• The useContent hook only works with .mdx files. It does not retrieve headings from .tsx files.
• The headings property contains an array of objects, each representing a heading with the following structure:
  • id: The unique identifier for the heading.
  • text: The text content of the heading.
  • level: The heading level (e.g., 1 for <h1>, 2 for <h2>, etc.).

When to Use

This feature is particularly useful for:

• Creating a dynamic table of contents for documentation pages.
• Building sidebar navigation for blog posts or articles.

For more details, refer to the useContent API documentation.