Back to Qwik

@builder.io/qwik-city API Reference

packages/docs/src/routes/api/qwik-city/index.mdx

1.7.143.0 KB
Original Source

API › @builder.io/qwik-city

<h2 id="action">Action</h2>
typescript
export type Action<
  RETURN,
  INPUT = Record<string, unknown>,
  OPTIONAL extends boolean = true,
> = {
  (): ActionStore<RETURN, INPUT, OPTIONAL>;
};

References: ActionStore

Edit this section

<h2 id="actionconstructor">ActionConstructor</h2>
typescript
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

<h2 id="actionreturn">ActionReturn</h2>
typescript
export type ActionReturn<RETURN> = {
  readonly status?: number;
  readonly value: RETURN;
};

Edit this section

<h2 id="actionstore">ActionStore</h2>
typescript
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

<h2 id="contentheading">ContentHeading</h2>
typescript
export interface ContentHeading
<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead> <tbody><tr><td>

id

</td><td>

readonly

</td><td>

string

</td><td> </td></tr> <tr><td>

level

</td><td>

readonly

</td><td>

number

</td><td> </td></tr> <tr><td>

text

</td><td>

readonly

</td><td>

string

</td><td> </td></tr> </tbody></table>

Edit this section

<h2 id="contentmenu">ContentMenu</h2>
typescript
export interface ContentMenu
<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead> <tbody><tr><td>

href?

</td><td>

readonly

</td><td>

string

</td><td>

(Optional)

</td></tr> <tr><td>

items?

</td><td>

readonly

</td><td>

ContentMenu[]

</td><td>

(Optional)

</td></tr> <tr><td>

text

</td><td>

readonly

</td><td>

string

</td><td> </td></tr> </tbody></table>

Edit this section

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

References: ValidatorReturn

Edit this section

<h2 id="documenthead">DocumentHead</h2>
typescript
export type DocumentHead =
  | DocumentHeadValue
  | ((props: DocumentHeadProps) => DocumentHeadValue);

References: DocumentHeadValue, DocumentHeadProps

Edit this section

<h2 id="documentheadprops">DocumentHeadProps</h2>
typescript
export interface DocumentHeadProps extends RouteLocation

Extends: RouteLocation

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead> <tbody><tr><td>

head

</td><td>

readonly

</td><td>

ResolvedDocumentHead

</td><td> </td></tr> <tr><td>

resolveValue

</td><td>

readonly

</td><td>

ResolveSyncValue

</td><td> </td></tr> <tr><td>

withLocale

</td><td>

readonly

</td><td>

<T>(fn: () => T) => T

</td><td> </td></tr> </tbody></table>

Edit this section

<h2 id="documentheadvalue">DocumentHeadValue</h2>
typescript
export interface DocumentHeadValue<FrontMatter extends Record<string, any> = Record<string, unknown>>
<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead> <tbody><tr><td>

frontmatter?

</td><td>

readonly

</td><td>

Readonly<FrontMatter>

</td><td>

(Optional) Arbitrary object containing custom data. When the document head is created from markdown files, the frontmatter attributes that are not recognized as a well-known meta names (such as title, description, author, etc...), are stored in this property.

</td></tr> <tr><td>

links?

</td><td>

readonly

</td><td>

readonly DocumentLink[]

</td><td>

(Optional) Used to manually append <link> elements to the <head>.

</td></tr> <tr><td>

meta?

</td><td>

readonly

</td><td>

readonly DocumentMeta[]

</td><td>

(Optional) Used to manually set meta tags in the head. Additionally, the data property could be used to set arbitrary data which the <head> component could later use to generate <meta> tags.

</td></tr> <tr><td>

scripts?

</td><td>

readonly

</td><td>

readonly DocumentScript[]

</td><td>

(Optional) Used to manually append <script> elements to the <head>.

</td></tr> <tr><td>

styles?

</td><td>

readonly

</td><td>

readonly DocumentStyle[]

</td><td>

(Optional) Used to manually append <style> elements to the <head>.

</td></tr> <tr><td>

title?

</td><td>

readonly

</td><td>

string

</td><td>

(Optional) Sets document.title.

</td></tr> </tbody></table>

Edit this section

<h2 id="documentlink">DocumentLink</h2>
typescript
export interface DocumentLink
<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead> <tbody><tr><td>

as?

</td><td> </td><td>

string

</td><td>

(Optional)

</td></tr> <tr><td>

crossorigin?

</td><td> </td><td>

string

</td><td>

(Optional)

</td></tr> <tr><td>

disabled?

</td><td> </td><td>

boolean

</td><td>

(Optional)

</td></tr> <tr><td>

href?

</td><td> </td><td>

string

</td><td>

(Optional)

</td></tr> <tr><td>

hreflang?

</td><td> </td><td>

string

</td><td>

(Optional)

</td></tr> <tr><td>

id?

</td><td> </td><td>

string

</td><td>

(Optional)

</td></tr> <tr><td>

imagesizes?

</td><td> </td><td>

string

</td><td>

(Optional)

</td></tr> <tr><td>

imagesrcset?

</td><td> </td><td>

string

</td><td>

(Optional)

</td></tr> <tr><td>

integrity?

</td><td> </td><td>

string

</td><td>

(Optional)

</td></tr> <tr><td>

key?

</td><td> </td><td>

string

</td><td>

(Optional)

</td></tr> <tr><td>

media?

</td><td> </td><td>

string

</td><td>

(Optional)

</td></tr> <tr><td>

prefetch?

</td><td> </td><td>

string

</td><td>

(Optional)

</td></tr> <tr><td>

referrerpolicy?

</td><td> </td><td>

string

</td><td>

(Optional)

</td></tr> <tr><td>

rel?

</td><td> </td><td>

string

</td><td>

(Optional)

</td></tr> <tr><td>

sizes?

</td><td> </td><td>

string

</td><td>

(Optional)

</td></tr> <tr><td>

title?

</td><td> </td><td>

string

</td><td>

(Optional)

</td></tr> <tr><td>

type?

</td><td> </td><td>

string

</td><td>

(Optional)

</td></tr> </tbody></table>

Edit this section

<h2 id="documentmeta">DocumentMeta</h2>
typescript
export interface DocumentMeta
<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead> <tbody><tr><td>

content?

</td><td>

readonly

</td><td>

string

</td><td>

(Optional)

</td></tr> <tr><td>

httpEquiv?

</td><td>

readonly

</td><td>

string

</td><td>

(Optional)

</td></tr> <tr><td>

itemprop?

</td><td>

readonly

</td><td>

string

</td><td>

(Optional)

</td></tr> <tr><td>

key?

</td><td>

readonly

</td><td>

string

</td><td>

(Optional)

</td></tr> <tr><td>

media?

</td><td>

readonly

</td><td>

string

</td><td>

(Optional)

</td></tr> <tr><td>

name?

</td><td>

readonly

</td><td>

string

</td><td>

(Optional)

</td></tr> <tr><td>

property?

</td><td>

readonly

</td><td>

string

</td><td>

(Optional)

</td></tr> </tbody></table>

Edit this section

<h2 id="documentscript">DocumentScript</h2>

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.

typescript
export interface DocumentScript
<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead> <tbody><tr><td>

key?

</td><td>

readonly

</td><td>

string

</td><td>

(ALPHA) (Optional)

</td></tr> <tr><td>

props?

</td><td>

readonly

</td><td>

Readonly<QwikIntrinsicElements['script']>

</td><td>

(ALPHA) (Optional)

</td></tr> <tr><td>

script?

</td><td>

readonly

</td><td>

string

</td><td>

(ALPHA) (Optional)

</td></tr> </tbody></table>

Edit this section

<h2 id="documentstyle">DocumentStyle</h2>
typescript
export interface DocumentStyle
<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead> <tbody><tr><td>

key?

</td><td>

readonly

</td><td>

string

</td><td>

(Optional)

</td></tr> <tr><td>

props?

</td><td>

readonly

</td><td>

Readonly<QwikIntrinsicElements['style']>

</td><td>

(Optional)

</td></tr> <tr><td>

style

</td><td>

readonly

</td><td>

string

</td><td> </td></tr> </tbody></table>

Edit this section

<h2 id="errorboundary">ErrorBoundary</h2>
typescript
ErrorBoundary: import("@builder.io/qwik").Component<ErrorBoundaryProps>;

Edit this section

<h2 id="failofrest">FailOfRest</h2>
typescript
export type FailOfRest<REST extends readonly DataValidator[]> =
  REST extends readonly DataValidator<infer ERROR>[] ? ERROR : never;

References: DataValidator

Edit this section

<h2 id="failreturn">FailReturn</h2>
typescript
export type FailReturn<T> = T & Failed;

Edit this section

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

Parameter

</th><th>

Type

</th><th>

Description

</th></tr></thead> <tbody><tr><td>

{ action, spaReset, reloadDocument, onSubmit$, ...rest }

</td><td>

FormProps<O, I>

</td><td> </td></tr> <tr><td>

key

</td><td>

string | null

</td><td> </td></tr> </tbody></table>

Returns:

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

Edit this section

<h2 id="formprops">FormProps</h2>
typescript
export interface FormProps<O, I> extends Omit<QwikJSX.IntrinsicElements['form'], 'action' | 'method'>

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

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead> <tbody><tr><td>

action?

</td><td> </td><td>

ActionStore<O, I, true | false>

</td><td>

(Optional) Reference to the action returned by action().

</td></tr> <tr><td>

key?

</td><td> </td><td>

string | number | null

</td><td>

(Optional)

</td></tr> <tr><td>

onSubmit$?

</td><td> </td><td>

QRLEventHandlerMulti<SubmitEvent, HTMLFormElement> | undefined

</td><td>

(Optional) Event handler executed right when the form is submitted.

</td></tr> <tr><td>

onSubmitCompleted$?

</td><td> </td><td>

QRLEventHandlerMulti<CustomEvent<FormSubmitCompletedDetail<O>>, HTMLFormElement> | undefined

</td><td>

(Optional) Event handler executed right after the action is executed successfully and returns some data.

</td></tr> <tr><td>

reloadDocument?

</td><td> </td><td>

boolean

</td><td>

(Optional) When true the form submission will cause a full page reload, even if SPA mode is enabled and JS is available.

</td></tr> <tr><td>

spaReset?

</td><td> </td><td>

boolean

</td><td>

(Optional) When true all the form inputs will be reset in SPA mode, just like happens in a full page form submission.

Defaults to false

</td></tr> </tbody></table>

Edit this section

<h2 id="formsubmitsuccessdetail">FormSubmitSuccessDetail</h2>
typescript
export interface FormSubmitCompletedDetail<T>
<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead> <tbody><tr><td>

status

</td><td> </td><td>

number

</td><td> </td></tr> <tr><td>

value

</td><td> </td><td>

T

</td><td> </td></tr> </tbody></table>

Edit this section

<h2 id="getvalidatorinputtype">GetValidatorInputType</h2>
typescript
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

<h2 id="getvalidatoroutputtype">GetValidatorOutputType</h2>
typescript
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

<h2 id="getvalidatortype">GetValidatorType</h2>
typescript
export type GetValidatorType<VALIDATOR extends TypedDataValidator> =
  GetValidatorOutputType<VALIDATOR>;

References: TypedDataValidator, GetValidatorOutputType

Edit this section

<h2 id="globalaction_">globalAction$</h2>
typescript
globalAction$: ActionConstructor;

Edit this section

<h2 id="globalactionqrl">globalActionQrl</h2>
typescript
globalActionQrl: ActionConstructorQRL;

Edit this section

<h2 id="jsonobject">JSONObject</h2>
typescript
export type JSONObject = {
  [x: string]: JSONValue;
};

References: JSONValue

Edit this section

<h2 id="jsonvalue">JSONValue</h2>
typescript
export type JSONValue =
  | string
  | number
  | boolean
  | {
      [x: string]: JSONValue;
    }
  | Array<JSONValue>;

References: JSONValue

Edit this section

<h2 id="link">Link</h2>
typescript
Link: import("@builder.io/qwik").Component<LinkProps>;

Edit this section

<h2 id="linkprops">LinkProps</h2>
typescript
export interface LinkProps extends AnchorAttributes

Extends: AnchorAttributes

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead> <tbody><tr><td>

prefetch?

</td><td> </td><td>

boolean | 'js'

</td><td>

(Optional) **Defaults to _true_.**

Whether Qwik should prefetch and cache the target page of this **Link**, this includes invoking any **routeLoader$**, **onGet**, etc.

This **improves UX performance** for client-side (**SPA**) navigations.

Prefetching occurs when a the Link enters the viewport in production (**on:qvisible**), or with **mouseover/focus** during dev.

Prefetching will not occur if the user has the **data saver** setting enabled.

Setting this value to **"js"** will prefetch only javascript bundles required to render this page on the client, **false** will disable prefetching altogether.

</td></tr> <tr><td>

reload?

</td><td> </td><td>

boolean

</td><td>

(Optional)

</td></tr> <tr><td>

replaceState?

</td><td> </td><td>

boolean

</td><td>

(Optional)

</td></tr> <tr><td>

scroll?

</td><td> </td><td>

boolean

</td><td>

(Optional)

</td></tr> </tbody></table>

Edit this section

<h2 id="loader_2">Loader_2</h2>
typescript
export type Loader<RETURN> = {
  (): LoaderSignal<RETURN>;
};

References: LoaderSignal

Edit this section

<h2 id="loadersignal">LoaderSignal</h2>
typescript
export type LoaderSignal<TYPE> = TYPE extends () => ValueOrPromise<
  infer VALIDATOR
>
  ? ReadonlySignal<ValueOrPromise<VALIDATOR>>
  : ReadonlySignal<TYPE>;

Edit this section

<h2 id="menudata">MenuData</h2>
typescript
export type MenuData = [pathname: string, menuLoader: MenuModuleLoader];

Edit this section

<h2 id="navigationtype">NavigationType</h2>
typescript
export type NavigationType = "initial" | "form" | "link" | "popstate";

Edit this section

<h2 id="pagemodule">PageModule</h2>
typescript
export interface PageModule extends RouteModule

Extends: RouteModule

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead> <tbody><tr><td>

default

</td><td>

readonly

</td><td>

unknown

</td><td> </td></tr> <tr><td>

head?

</td><td>

readonly

</td><td>

ContentModuleHead

</td><td>

(Optional)

</td></tr> <tr><td>

headings?

</td><td>

readonly

</td><td>

ContentHeading[]

</td><td>

(Optional)

</td></tr> <tr><td>

onStaticGenerate?

</td><td>

readonly

</td><td>

StaticGenerateHandler

</td><td>

(Optional)

</td></tr> </tbody></table>

Edit this section

<h2 id="pathparams">PathParams</h2>
typescript
export declare type PathParams = Record<string, string>;

Edit this section

<h2 id="preventnavigatecallback">PreventNavigateCallback</h2>
typescript
export type PreventNavigateCallback = (
  url?: number | URL,
) => ValueOrPromise<boolean>;

Edit this section

<h2 id="qwik_city_scroller">QWIK_CITY_SCROLLER</h2>
typescript
QWIK_CITY_SCROLLER = "_qCityScroller";

Edit this section

<h2 id="qwikcitymockactionprop">QwikCityMockActionProp</h2>
typescript
export interface QwikCityMockActionProp<T = any>
<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead> <tbody><tr><td>

action

</td><td> </td><td>

Action<T>

</td><td>

The action function to mock.

</td></tr> <tr><td>

handler

</td><td> </td><td>

QRL<(data: T) => ValueOrPromise<RouteActionResolver>>

</td><td>

The QRL function that will be called when the action is submitted.

</td></tr> </tbody></table>

Edit this section

<h2 id="qwikcitymockloaderprop">QwikCityMockLoaderProp</h2>
typescript
export interface QwikCityMockLoaderProp<T = any>
<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead> <tbody><tr><td>

data

</td><td> </td><td>

T

</td><td>

The data to return when the loader is called.

</td></tr> <tr><td>

loader

</td><td> </td><td>

Loader<T>

</td><td>

The loader function to mock.

</td></tr> </tbody></table>

Edit this section

<h2 id="qwikcitymockprops">QwikCityMockProps</h2>
typescript
export interface QwikCityMockProps
<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead> <tbody><tr><td>

actions?

</td><td> </td><td>

Array<QwikCityMockActionProp<any>>

</td><td>

(Optional) Allow mocking actions defined with routeAction$ function.

[
  {
    action: useAddUser,
    handler: $(async (data) => {
      console.log('useAddUser action called with data:', data);
    }),
  },
];
</td></tr> <tr><td>

goto?

</td><td> </td><td>

RouteNavigate

</td><td>

(Optional) Allow mocking the goto function returned by useNavigate hook.

</td></tr> <tr><td>

loaders?

</td><td> </td><td>

Array<QwikCityMockLoaderProp<any>>

</td><td>

(Optional) Allow mocking data for loaders defined with routeLoader$ function.

[
  {
    loader: useProductData,
    data: { product: { name: 'Test Product' } },
  },
];
</td></tr> <tr><td>

params?

</td><td> </td><td>

Record<string, string>

</td><td>

(Optional) Allow mocking the route params returned by useLocation hook.

</td></tr> <tr><td>

url?

</td><td> </td><td>

string

</td><td>

(Optional) Allow mocking the url returned by useLocation hook.

Default: http://localhost/

</td></tr> </tbody></table>

Edit this section

<h2 id="qwikcitymockprovider">QwikCityMockProvider</h2>
typescript
QwikCityMockProvider: import("@builder.io/qwik").Component<QwikCityMockProps>;

Edit this section

<h2 id="qwikcityplan">QwikCityPlan</h2>
typescript
export interface QwikCityPlan
<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead> <tbody><tr><td>

basePathname?

</td><td>

readonly

</td><td>

string

</td><td>

(Optional)

</td></tr> <tr><td>

cacheModules?

</td><td>

readonly

</td><td>

boolean

</td><td>

(Optional)

</td></tr> <tr><td>

menus?

</td><td>

readonly

</td><td>

MenuData[]

</td><td>

(Optional)

</td></tr> <tr><td>

routes

</td><td>

readonly

</td><td>

RouteData[]

</td><td> </td></tr> <tr><td>

serverPlugins?

</td><td>

readonly

</td><td>

RouteModule[]

</td><td>

(Optional)

</td></tr> <tr><td>

trailingSlash?

</td><td>

readonly

</td><td>

boolean

</td><td>

(Optional)

</td></tr> </tbody></table>

Edit this section

<h2 id="qwikcityprops">QwikCityProps</h2>
typescript
export interface QwikCityProps
<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead> <tbody><tr><td>

viewTransition?

</td><td> </td><td>

boolean

</td><td>

(Optional) Enable the ViewTransition API

Default: true

</td></tr> </tbody></table>

Edit this section

<h2 id="qwikcityprovider">QwikCityProvider</h2>
typescript
QwikCityProvider: import("@builder.io/qwik").Component<QwikCityProps>;

Edit this section

<h2 id="resolveddocumenthead">ResolvedDocumentHead</h2>
typescript
export type ResolvedDocumentHead<
  FrontMatter extends Record<string, any> = Record<string, unknown>,
> = Required<DocumentHeadValue<FrontMatter>>;

References: DocumentHeadValue

Edit this section

<h2 id="routeaction_">routeAction$</h2>
typescript
routeAction$: ActionConstructor;

Edit this section

<h2 id="routeactionqrl">routeActionQrl</h2>
typescript
routeActionQrl: ActionConstructorQRL;

Edit this section

<h2 id="routedata">RouteData</h2>
typescript
export type RouteData =
  | [routeName: string, loaders: ModuleLoader[]]
  | [
      routeName: string,
      loaders: ModuleLoader[],
      originalPathname: string,
      routeBundleNames: string[],
    ];

Edit this section

<h2 id="routeloader_">routeLoader$</h2>
typescript
routeLoader$: LoaderConstructor;

Edit this section

<h2 id="routeloaderqrl">routeLoaderQrl</h2>
typescript
routeLoaderQrl: LoaderConstructorQRL;

Edit this section

<h2 id="routelocation">RouteLocation</h2>
typescript
export interface RouteLocation
<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead> <tbody><tr><td>

isNavigating

</td><td>

readonly

</td><td>

boolean

</td><td> </td></tr> <tr><td>

params

</td><td>

readonly

</td><td>

Readonly<Record<string, string>>

</td><td> </td></tr> <tr><td>

prevUrl

</td><td>

readonly

</td><td>

URL | undefined

</td><td> </td></tr> <tr><td>

url

</td><td>

readonly

</td><td>

URL

</td><td> </td></tr> </tbody></table>

Edit this section

<h2 id="routenavigate">RouteNavigate</h2>
typescript
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

<h2 id="routeroutlet">RouterOutlet</h2>
typescript
RouterOutlet: import("@builder.io/qwik").Component<unknown>;

Edit this section

<h2 id="server_">server$</h2>
typescript
server$: <T extends ServerFunction>(
  qrl: T,
  options?: ServerConfig | undefined,
) => ServerQRL<T>;
<table><thead><tr><th>

Parameter

</th><th>

Type

</th><th>

Description

</th></tr></thead> <tbody><tr><td>

qrl

</td><td>

T

</td><td> </td></tr> <tr><td>

options

</td><td>

ServerConfig | undefined

</td><td>

(Optional)

</td></tr> </tbody></table>

Returns:

ServerQRL<T>

Edit this section

<h2 id="serverfunction">ServerFunction</h2>
typescript
export type ServerFunction = {
  (this: RequestEventBase, ...args: any[]): any;
  options?: ServerConfig;
};

Edit this section

<h2 id="serverqrl-function">serverQrl</h2>

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

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

References: ServerFunction

Edit this section

<h2 id="serverqrl-type-alias">ServerQRL</h2>

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

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

References: ServerFunction

Edit this section

<h2 id="serviceworkerregister">ServiceWorkerRegister</h2>

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.

typescript
ServiceWorkerRegister: (props: { nonce?: string }) => JSXOutput;
<table><thead><tr><th>

Parameter

</th><th>

Type

</th><th>

Description

</th></tr></thead> <tbody><tr><td>

props

</td><td>

{ nonce?: string; }

</td><td> </td></tr> </tbody></table>

Returns:

JSXOutput

Edit this section

<h2 id="staticgenerate">StaticGenerate</h2>
typescript
export interface StaticGenerate
<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead> <tbody><tr><td>

params?

</td><td> </td><td>

PathParams[]

</td><td>

(Optional)

</td></tr> </tbody></table>

Edit this section

<h2 id="staticgeneratehandler">StaticGenerateHandler</h2>
typescript
export type StaticGenerateHandler = ({
  env,
}: {
  env: EnvGetter;
}) => Promise<StaticGenerate> | StaticGenerate;

References: StaticGenerate

Edit this section

<h2 id="strictunion">StrictUnion</h2>
typescript
export type StrictUnion<T> = Prettify<StrictUnionHelper<T, T>>;

Edit this section

<h2 id="typeddatavalidator">TypedDataValidator</h2>
typescript
export type TypedDataValidator = ValibotDataValidator | ZodDataValidator;

Edit this section

<h2 id="usecontent">useContent</h2>
typescript
useContent: () => import("./types").ContentState;

Returns:

import("./types").ContentState

Edit this section

<h2 id="usedocumenthead">useDocumentHead</h2>

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

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

Returns:

Required<ResolvedDocumentHead<FrontMatter>>

Edit this section

<h2 id="uselocation">useLocation</h2>
typescript
useLocation: () => RouteLocation;

Returns:

RouteLocation

Edit this section

<h2 id="usenavigate">useNavigate</h2>
typescript
useNavigate: () => RouteNavigate;

Returns:

RouteNavigate

Edit this section

<h2 id="usepreventnavigate_">usePreventNavigate$</h2>

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.

typescript
usePreventNavigate$: (qrl: PreventNavigateCallback) => void
<table><thead><tr><th>

Parameter

</th><th>

Type

</th><th>

Description

</th></tr></thead> <tbody><tr><td>

qrl

</td><td>

PreventNavigateCallback

</td><td> </td></tr> </tbody></table>

Returns:

void

Edit this section

<h2 id="valibot_">valibot$</h2>

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.

typescript
valibot$: ValibotConstructor;

Edit this section

<h2 id="valibotqrl">valibotQrl</h2>

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.

typescript
valibotQrl: ValibotConstructorQRL;

Edit this section

<h2 id="validator_">validator$</h2>
typescript
validator$: ValidatorConstructor;

Edit this section

<h2 id="validatorerrorkeydotnotation">ValidatorErrorKeyDotNotation</h2>
typescript
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

<h2 id="validatorerrortype">ValidatorErrorType</h2>
typescript
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

<h2 id="validatorqrl">validatorQrl</h2>
typescript
validatorQrl: ValidatorConstructorQRL;

Edit this section

<h2 id="validatorreturn">ValidatorReturn</h2>
typescript
export type ValidatorReturn<T extends Record<string, any> = {}> =
  | ValidatorReturnSuccess
  | ValidatorReturnFail<T>;

Edit this section

<h2 id="zod_">zod$</h2>
typescript
zod$: ZodConstructor;

Edit this section

<h2 id="zodconstructor">ZodConstructor</h2>
typescript
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

<h2 id="zodqrl">zodQrl</h2>
typescript
zodQrl: ZodConstructorQRL;

Edit this section