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

Property	Modifiers	Type
id	`readonly`	string
level	`readonly`	number
text	`readonly`	string

Edit this section

ContentMenu

export interface ContentMenu

Property	Modifiers	Type	Description
href?	`readonly`	string	(Optional)
items?	`readonly`	ContentMenu[]	(Optional)
text	`readonly`	string

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

Property	Modifiers	Type
head	`readonly`	ResolvedDocumentHead
resolveValue	`readonly`	ResolveSyncValue
withLocale	`readonly`	<T>(fn: () => T) => T

Edit this section

DocumentHeadValue

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

Property	Modifiers	Type	Description
frontmatter?	`readonly`	Readonly<FrontMatter>	(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.
links?	`readonly`	readonly DocumentLink[]	(Optional) Used to manually append `<link>` elements to the `<head>`.
meta?	`readonly`	readonly DocumentMeta[]	(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.
scripts?	`readonly`	readonly DocumentScript[]	(Optional) Used to manually append `<script>` elements to the `<head>`.
styles?	`readonly`	readonly DocumentStyle[]	(Optional) Used to manually append `<style>` elements to the `<head>`.
title?	`readonly`	string	(Optional) Sets `document.title`.

Edit this section

DocumentLink

export interface DocumentLink

Property	Type	Description
as?	string	(Optional)
crossorigin?	string	(Optional)
disabled?	boolean	(Optional)
href?	string	(Optional)
hreflang?	string	(Optional)
id?	string	(Optional)
imagesizes?	string	(Optional)
imagesrcset?	string	(Optional)
integrity?	string	(Optional)
key?	string	(Optional)
media?	string	(Optional)
prefetch?	string	(Optional)
referrerpolicy?	string	(Optional)
rel?	string	(Optional)
sizes?	string	(Optional)
title?	string	(Optional)
type?	string	(Optional)

Edit this section

DocumentMeta

export interface DocumentMeta

Property	Modifiers	Type	Description
content?	`readonly`	string	(Optional)
httpEquiv?	`readonly`	string	(Optional)
itemprop?	`readonly`	string	(Optional)
key?	`readonly`	string	(Optional)
media?	`readonly`	string	(Optional)
name?	`readonly`	string	(Optional)
property?	`readonly`	string	(Optional)

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

Property	Modifiers	Type	Description
key?	`readonly`	string	*(ALPHA)* (Optional)
props?	`readonly`	Readonly<QwikIntrinsicElements['script']>	*(ALPHA)* (Optional)
script?	`readonly`	string	*(ALPHA)* (Optional)

Edit this section

DocumentStyle

export interface DocumentStyle

Property	Modifiers	Type	Description
key?	`readonly`	string	(Optional)
props?	`readonly`	Readonly<QwikIntrinsicElements['style']>	(Optional)
style	`readonly`	string

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;

Parameter	Type	Description
{ action, spaReset, reloadDocument, onSubmit$, ...rest }	FormProps<O, I>
key	string \| null

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'>

Property	Type	Description
action?	ActionStore<O, I, true \| false>	(Optional) Reference to the action returned by `action()`.
key?	string \| number \| null	(Optional)
onSubmit$?	QRLEventHandlerMulti<SubmitEvent, HTMLFormElement> \| undefined	(Optional) Event handler executed right when the form is submitted.
onSubmitCompleted$?	QRLEventHandlerMulti<CustomEvent<FormSubmitCompletedDetail<O>>, HTMLFormElement> \| undefined	(Optional) Event handler executed right after the action is executed successfully and returns some data.
reloadDocument?	boolean	(Optional) When `true` the form submission will cause a full page reload, even if SPA mode is enabled and JS is available.
spaReset?	boolean	(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`

Edit this section

FormSubmitSuccessDetail

export interface FormSubmitCompletedDetail<T>

Property	Modifiers	Type	Description
status		number
value		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

Property	Type	Description
prefetch?	boolean \| 'js'	(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:qvisibile`), 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.
reload?	boolean	(Optional)
replaceState?	boolean	(Optional)
scroll?	boolean	(Optional)

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

Property	Modifiers	Type	Description
default	`readonly`	unknown
head?	`readonly`	ContentModuleHead	(Optional)
headings?	`readonly`	ContentHeading[]	(Optional)
onStaticGenerate?	`readonly`	StaticGenerateHandler	(Optional)

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

Property	Type	Description
goto?	RouteNavigate	(Optional)
params?	Record<string, string>	(Optional)
url?	string	(Optional)

Edit this section

QwikCityMockProvider

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

Edit this section

QwikCityPlan

export interface QwikCityPlan

Property	Modifiers	Type	Description
basePathname?	`readonly`	string	(Optional)
cacheModules?	`readonly`	boolean	(Optional)
menus?	`readonly`	MenuData[]	(Optional)
routes	`readonly`	RouteData[]
serverPlugins?	`readonly`	RouteModule[]	(Optional)
trailingSlash?	`readonly`	boolean	(Optional)

Edit this section

QwikCityProps

export interface QwikCityProps

Property	Modifiers	Type	Description
viewTransition?		boolean	(Optional) Enable the ViewTransition API Default: `true`

Property

Modifiers

Type

Description

viewTransition?

boolean

(Optional) Enable the ViewTransition API

Default: true

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

Property	Modifiers	Type
isNavigating	`readonly`	boolean
params	`readonly`	Readonly<Record<string, string>>
prevUrl	`readonly`	URL \| undefined
url	`readonly`	URL

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>;

Parameter	Type	Description
qrl	T
options	ServerConfig \| undefined	(Optional)

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.

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

Parameter	Type	Description
props	{ nonce?: string; }

Returns:

JSXOutput

Edit this section

StaticGenerate

export interface StaticGenerate

Property	Modifiers	Type	Description
params?		PathParams[]	(Optional)

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

Parameter	Type	Description
qrl	PreventNavigateCallback

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