Builder appState options

The appState variable can be used within custom plugins to interact with key Builder features or to gather important contextual data.

Import appState

Import appState in the following way:

import appState from "@builder.io/app-context";

The appState variable represents the application's current state. It is intended for use within the Visual Editor.

The appState variable has several key-value pairs and methods. The most commonly used are detailed below.

appState.user

The appState.user key provides valuable data and tools for the current user.

interface AppStateUser { id: string; // The current user's Builder ID apiKey: string; // The org's public API key // Pre-built auth headers for authenticated requests authHeaders: { [key: string]: string }; // Check if the current user has a given permission can(permissionType: 'editCode' | 'admin' | 'editDesigns' | 'createContent' | 'publish'): boolean; // Fetch another user's details by ID, or null if not found getUser(id: string): Promise<{ id: string; email: string } | null>; // List all users in the current organization listUsers(): Promise<{ id: string; email: string }[]>; // Log the current user out signOut(): void; }

appState.designerState

The appState.designerState key provides key-value pairs and methods related to the Visual Editor.

interface AppStateDesignerState { // Current content entry. Is `null` if none. editingContentModel: { id: string; name: string; url?: string; lastUpdated: Date; allBlocks?: BuilderElement[]; // MobX observable Maps -- use .get()/.set() meta: Map<string, any>; data: Map<string, any>; } | null; editingIframeRef: HTMLIFrameElement | null; artboardSize: { width: number }; draggingInItem: BuilderElement | Component | string | null; xrayMode: boolean; canUndo: boolean; canRedo: boolean; undo(): Promise<void>; redo(): Promise<void>; // Returns true if the current content has unsaved changes hasUnsavedChanges(): boolean; // Saves a checkpoint of the current editing state createCheckpoint(): Promise<void>; }

appState.models

The appState.models key contains key-value pairs and methods for all models within the organization.

interface AppStateModels { // All models defined in the current organization result: { id: string; name: string; fields: Input[]; /* Observable array Use .replace(newArr) to swap contents */ webhooks: any[]; }[]; /* CAREFUL: Persist model changes to the backend. Pass 'false' as second argument to suppress confirmation. */ update(model: Model, confirm?: boolean): Promise<void>; // CAREFUL: Permanently deletes a model. remove(model: Model): Promise<void>; }

Note: Both .update() and .remove() are destructive methods. Be extremely careful with changes, as data cannot be recovered.

appState.dialogs

The appState.dialogs key contains methods for using Builder-style prompts, alerts, and confirmations.

interface AppStateDialogs { /* Show a text input prompt dialog. Resolves with the entered string */ prompt(options: { title?: string; text?: string; confirmText?: string; cancelText?: string; placeholderText?: string; defaultValue?: string; }): Promise<string>; // Show an alert dialog with an optional title alert(text: string, title?: string): Promise<null>; // Show a confirmation dialog, resolves with true/false confirm(message: string | { message: string }, confirmButtonText?: string): Promise<boolean>; }

appState.globalState

The appState.dialogs key contains methods for using Builder-style prompts, alerts, and confirmations.

interface AppStateGlobalState { // Show full-screen blocking loader with optional message showGlobalBlockingLoading(message?: string): void; // Hide the blocking loading spinner hideGlobalBlockingLoading(): void; // Alternative boolean toggle for the loading spinner showGlobalBlockingLoadingIndicator: boolean; /* Open a React element in a modal. Resolves with a function to close it. */ openDialog(element: JSX.Element): Promise<() => void>; // Retrieve the private key stored for a given plugin ID getPluginPrivateKey(pluginId: string): Promise<string | null>; /* Observable that fires when the user switches organizations. Call .subscribe() to react. */ orgSwitched?: { subscribe(callback: () => void): void }; /* Open a content picker dialog filtered to a specific model. Resolves with the selected content ID. */ showContentPickerDialog(options: { message: string; modelId: string }): Promise<string | null>; }

What's next

Was this article helpful?