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

Property

Modifiers

Type

Description

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

Description

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

export interface DocumentLink

Property

Modifiers

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

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

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

Modifiers

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: import("@builder.io/qwik").Component<LinkProps>;

Edit this section

LinkProps

export interface LinkProps extends AnchorAttributes

Extends: AnchorAttributes

Property

Modifiers

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

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

Edit this section

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

Modifiers

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

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

Description

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)

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

ServiceWorkerRegister: (props: { nonce?: string }) =>
  import("@builder.io/qwik").JSXNode<"script">;

Parameter

Type

Description

props

{ nonce?: string; }

import("@builder.io/qwik").JSXNode<"script">

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

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