The appState variable can be used within custom plugins to interact with key Builder features or to gather important contextual data.
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.
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;
}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>;
}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.
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>;
}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>;
}