Interface StudioAppOptions

Options for useStudioApp: the app's own (what to open, the startup dialog, the window chrome) plus any Studio prop, passed through to the returned props — so the hook's result is the whole <Studio> spread. workbook is spelled StudioAppOptions.source here, since the app's source may also be a string.

interface StudioAppOptions {
    autoFocus?: boolean | FocusOptions;
    confirmOnClose?: boolean;
    cssBaseline?: boolean;
    documentTitle?: string | boolean;
    editable?: SheetEditable;
    formulaBarPlacement?: "auto" | FormulaBarPlacement;
    keyboardGuard?: boolean | string[];
    licenseKey?: string;
    logo?: ReactNode;
    muiTheme?: ThemeOptions;
    onDirtyChange?: (isDirty: boolean) => void;
    onDocumentError?: (error: any) => void;
    onRenderSettled?: (event: WorkbookRenderSettledEvent) => void;
    onWorkbookChange?: (workbook: IWorkbook | null) => void;
    onWorkbookLoad?: (event: WorkbookLoadEvent) => void | Promise<void>;
    prefetch?: boolean | "auto";
    propsDocumentError?: Partial<ErrorPanelProps>;
    propsDocumentLoading?: Partial<LoadingPanelProps>;
    propsDocumentTitle?: DocumentTitleProps;
    propsFormulaBar?: Partial<FormulaBarProps>;
    propsStatusBar?: Partial<StatusBarProps>;
    propsTaskPaneArea?: Partial<TaskPaneAreaProps<any>>;
    propsToolbar?: Partial<WorkbookToolbarsProps>;
    propsWorkbook?: Partial<WorkbookElementProps>;
    renderDocumentError?: RenderSlotFn<ErrorPanelProps> | null;
    renderDocumentLoading?: RenderSlotFn<LoadingPanelProps> | null;
    renderFormulaBar?: RenderSlotFn<FormulaBarProps> | null;
    renderStatusBar?: RenderSlotFn<StatusBarProps> | null;
    renderTaskPaneArea?: RenderSlotFn<TaskPaneAreaProps<any>>;
    renderToolbar?: RenderSlotFn<WorkbookToolbarsProps> | null;
    showFormulaBar?: boolean;
    showStatusBar?: boolean;
    source?: StudioAppSource;
    startWith?: "welcome";
    sx?: SxProps<Theme>;
    taskPaneSide?: "left" | "right";
    templatePath?: string;
    tokens?: Partial<
        Record<
            ThemeMode,
            Partial<Record<ExplicitSurface, Partial<TokenTheme>>>,
        >,
    >;
    topLeft?: ReactNode;
    topRight?: ReactNode;
    virtualKeyboard?: VirtualKeyboardMode;
}

Hierarchy

WindowChromeOptions
Omit<StudioProps, "workbook">
- StudioAppOptions

Properties

`Optional`autoFocus

autoFocus?: boolean | FocusOptions

Autofocus on load. If loading multiple workbooks or using an a secondary component this should be set to false.

Default Value

false

`Optional`confirmOnClose

confirmOnClose?: boolean

When true (default), install a beforeunload guard that prompts the browser's "leave site / unsaved changes" dialog while the workbook is dirty.

`Optional`cssBaseline

cssBaseline?: boolean

Also apply the MUI CssBaseline when theming.

Default Value

false

`Optional`documentTitle

documentTitle?: string | boolean

Manage document.title from the workbook name + a leading ● when there are unsaved changes.

true (default): capture the current document.title as the base (e.g. the app name).
a string: use it as the base.
false: leave document.title alone.

The title becomes "<name> - <base>" (or just "<base>" for an unnamed workbook), with a leading "● " while dirty.

`Optional`editable

editable?: SheetEditable

The shared cell editor. Supply a stable SheetEditable to drive the grid and formula bar through one instance (free two-way sync); omit to let the studio auto-create one.

`Optional`formulaBarPlacement

formulaBarPlacement?: "auto" | FormulaBarPlacement

Where the formula bar sits: above the grid, or below it directly above the status bar, the way a phone spreadsheet lays it out.

Default Value

'auto' — 'bottom' on a device whose primary pointer is a finger (a phone, a tablet), 'top' everywhere else, including on the server.

Remarks

'auto' reads the device's primary pointer once, not the live input: a tablet that gets a mouse plugged in keeps its bar where it is. Force a value to develop the phone layout under device emulation, or when the host knows better than the device test.

`Optional`keyboardGuard

keyboardGuard?: boolean | string[]

Suppress browser keyboard shortcuts so they don't fire the browser instead of the app.

true (default): the DEFAULT_GUARD_KEYS (Ctrl/Cmd + O/S/W/N/T/M) plus Alt+Arrows.
a string array: those keys (with Ctrl/Cmd), plus Alt+Arrows.
false: don't touch the keyboard.

`Optional`licenseKey

licenseKey?: string

Set the license key via a property

Remarks

This will only be used the first time.

`Optional`logo

logo?: ReactNode

Custom logo.

`Optional`muiTheme

muiTheme?: ThemeOptions

MUI theme customization (ThemeOptions) merged into Studio's built-in light and dark themes — shared config (e.g. typography) plus per-mode overrides via MUI's native colorSchemes: { light, dark } (the modern replacement for the former lightTheme/darkTheme props):

muiTheme={{
  typography: { fontFamily: '…' },                          // both modes
  colorSchemes: {
    light: { palette: { primary: { main: '#6d28d9' } } },   // light only
    dark:  { palette: { primary: { main: '#a78bfa' } } },   // dark only
  },
}}

Remarks

This is config, not state. Light/dark mode and the dark-grid/dark-image toggles are self-managed by Studio as persisted preferences (see @sheetxl/react!ThemeStateKey), driven by the surrounding PersistentStateProvider — not by props. tokens layers token values on top.

`Optional`onDirtyChange

onDirtyChange?: (isDirty: boolean) => void

Called when the workbook's unsaved-changes (dirty) state changes.

Type Declaration

- (isDirty: boolean): void
- Parameters
  - isDirty: boolean
    true when there are unsaved changes since the last save (or the workbook was created), false when saved or undone back to the saved state.
  Returns void

Remarks

Use this to drive a host's "unsaved" affordances — a beforeunload close prompt, a tab marker, etc. (see the studio example). Save state is computed from the transaction store, so undoing back to the saved point reports clean again.

`Optional`onDocumentError

onDocumentError?: (error: any) => void

Called if the document (a promise / read options) fails to resolve.

Type Declaration

- (error: any): void
- Parameters
  - error: any
    The error
  Returns void

`Optional`onRenderSettled

onRenderSettled?: (event: WorkbookRenderSettledEvent) => void

Called when a workbook is shown: its first screen has finished drawing, or propsWorkbook.renderSettleTimeout ran out. Fires again for each workbook opened in the studio.

See

WorkbookElementProps.onRenderSettled

`Optional`onWorkbookChange

onWorkbookChange?: (workbook: IWorkbook | null) => void

Called when the studio's live workbook changes — e.g. when a workbook is opened (replacing the current one) via the Studio's own file commands or drag-and-drop, or on unmount (null).

Type Declaration

- (workbook: IWorkbook | null): void
- Parameters
  - workbook: IWorkbook | null
    The current workbook (carrying its origin + display name), or null.
  Returns void

Remarks

The Studio owns Open/replace internally, so a host that manages window-level chrome (tab title, beforeunload, see @sheetxl/studio-mui!useStudioApp) must observe this workbook rather than the one it resolved initially — otherwise the title/dirty guard stay bound to the first workbook after an in-app open. Pair with StudioProps.onDirtyChange for the unsaved flag.

`Optional`onWorkbookLoad

onWorkbookLoad?: (event: WorkbookLoadEvent) => void | Promise<void>

The app's own onWorkbookLoad handler, run after the startup dialog. (The hook also chains your onWorkbookChange / onDirtyChange, which it needs for the window chrome.)

`Optional`prefetch

prefetch?: boolean | "auto"

Whether features are loaded ahead of use once the studio is showing, so their first use does not wait on the network; see WorkbookElementProps.prefetch.

Remarks

The script editor and its compiler are always loaded on first use.

Default Value

'auto'

`Optional`propsDocumentError

propsDocumentError?: Partial<ErrorPanelProps>

Customizations for the default error panel shown when the StudioProps.document fails to resolve. Use StudioProps.renderDocumentError to replace the panel entirely.

`Optional`propsDocumentLoading

propsDocumentLoading?: Partial<LoadingPanelProps>

Customizations for the default loading panel shown while the StudioProps.document resolves (and the grid first paints). Use StudioProps.renderDocumentLoading to replace it entirely.

`Optional`propsDocumentTitle

propsDocumentTitle?: DocumentTitleProps

Additional document-title (title bar) properties.

Remarks

If onTitleChange or title is provided then the prop versions are ignored

`Optional`propsFormulaBar

propsFormulaBar?: Partial<FormulaBarProps>

Customizations for the formula bar.

`Optional`propsStatusBar

propsStatusBar?: Partial<StatusBarProps>

Customizations for the status bar.

`Optional`propsTaskPaneArea

propsTaskPaneArea?: Partial<TaskPaneAreaProps<any>>

Allow for customizations on TaskPaneArea.

`Optional`propsToolbar

propsToolbar?: Partial<WorkbookToolbarsProps>

Customizations for the toolbar.

`Optional`propsWorkbook

propsWorkbook?: Partial<WorkbookElementProps>

Customizations forwarded to the underlying (chromeless) workbook grid.

Remarks

The studio composes its chrome (toolbar / formula bar / status bar / menus) around the grid and forwards these to it. Grid-level concerns (sheet, tabs, context menus, scrollbars, etc.) live here rather than flat on StudioProps — the same containment pattern WorkbookElementProps uses for propsSheet.

`Optional`renderDocumentError

renderDocumentError?: RenderSlotFn<ErrorPanelProps> | null

Replace the error panel shown when the StudioProps.document fails to resolve (or cannot be rendered).

Remarks

The failure is also reported programmatically via StudioProps.onDocumentError.

Default Value

StackTraceErrorPanel

`Optional`renderDocumentLoading

renderDocumentLoading?: RenderSlotFn<LoadingPanelProps> | null

Replace the loading panel shown while the StudioProps.document resolves / the grid paints. null for none.

`Optional`renderFormulaBar

renderFormulaBar?: RenderSlotFn<FormulaBarProps> | null

Render a custom formula bar (replaces the default).

`Optional`renderStatusBar

renderStatusBar?: RenderSlotFn<StatusBarProps> | null

Render a custom status bar (replaces the default).

`Optional`renderTaskPaneArea

renderTaskPaneArea?: RenderSlotFn<TaskPaneAreaProps<any>>

Render the task pane area. Pass props.ref on to the ITaskPaneAreaElement.

Param: props

The properties for the TaskPaneArea.

`Optional`renderToolbar

renderToolbar?: RenderSlotFn<WorkbookToolbarsProps> | null

Render a custom toolbar (replaces the default studio toolbar).

`Optional`showFormulaBar

showFormulaBar?: boolean

Indicate if the formula bar should be showing.

Default Value

Workbook view model (but can be overridden).

`Optional`showStatusBar

showStatusBar?: boolean

Shows the status bar.

Default Value

Workbook view model (but can be overridden).

`Optional`source

source?: StudioAppSource

What to open. If omitted, the ?source / ?title URL query is read (with a #fragment for the sheet or cells to open at), else a blank workbook is created. See StudioAppSource.

`Optional`startWith

startWith?: "welcome"

What to show when the app starts with no source. 'welcome' opens the welcome dialog (start blank, open a workbook, or pick a template) over the blank workbook.

Default Value

nothing; the blank workbook is shown

`Optional`sx

sx?: SxProps<Theme>

MUI SX props https://mui.com/system/getting-started/the-sx-prop/

`Optional`taskPaneSide

taskPaneSide?: "left" | "right"

Allow for a side of the taskpane.

Default Value

'right'

`Optional`templatePath

templatePath?: string

The template catalog the welcome and "Choose a template" dialogs show: a URL serving templates-workbook/contents.json. Use it to pin a version or to serve your own templates.

Default Value

the latest published @sheetxl/templates-workbook

`Optional`tokens

tokens?: Partial<
Record<ThemeMode, Partial<Record<ExplicitSurface, Partial<TokenTheme>>>>,
>

Explicit --sxl-* token values — the host's own colors, stated rather than derived. Addressed by cell: a (surface × mode) pair, so a host can name the header paper without a new token existing:

tokens={{
  dark: {
    app: {
      'color-base-200': '#1f1f1f',                 // the chrome/desktop surface
      'color-input': '#313131',                    // the formula bar / name box field
      'color-input-border': '#3c3c3c',
    },
    header: { 'color-base-100': '#181818' },       // the row/column header paper
  },
}}

Remarks

Use this — not muiTheme — for anything the MUI palette has no slot for. Studio derives what you leave unset (gridlines, the header hover step) from the five palette slots by elevation math, which assumes "raised" means "lighter". A flat design language (VS Code, Fluent) names those surfaces outright and does not follow that curve, so stating them here makes the derivation stand down for exactly those cells and keeps deriving only the rest.

The surfaces are app (the default cell everything inherits), header (row/column headers) and grid (the cell body). These are emitted with Studio's own sxl-app layer, so they stay surface-aware. The app cell also retints the MUI chrome (primary, background, text, radius, font). A stylesheet in @layer sxl-overrides reaches the grid but not the MUI chrome.

`Optional`topLeft

topLeft?: ReactNode

Slot rendered at the top-left of the toolbar (after the logo, before the title).

Remarks

Application-level toolbar chrome the studio no longer hardcodes — e.g. a file menu. Inject a @sheetxl/studio-mui!StandaloneFileCommandButton for the standalone file menu (open / save / import / export); command availability is still governed by the active WorkbookIO backing store's canRead / canWrite.

`Optional`topRight

topRight?: ReactNode

Slot rendered at the top-right of the toolbar — e.g. an appearance (light/dark) menu. Inject an @sheetxl/studio-mui!AppearanceCommandButton for the default appearance menu.

`Optional`virtualKeyboard

virtualKeyboard?: VirtualKeyboardMode

How the studio makes room for the virtual keyboard. See StudioProps.virtualKeyboard.

Default Value

'resize': the app owns the window, so the studio shrinks to the part of the screen the keyboard leaves

Interface StudioAppOptions

Hierarchy

Index

Properties

Properties

OptionalautoFocus

Default Value

OptionalconfirmOnClose

OptionalcssBaseline

Default Value

OptionaldocumentTitle

Optionaleditable

OptionalformulaBarPlacement

Default Value

Remarks

OptionalkeyboardGuard

OptionallicenseKey

Remarks

Optionallogo

OptionalmuiTheme

Remarks

OptionalonDirtyChange

Type Declaration

Parameters

Returns void

Remarks

OptionalonDocumentError

Type Declaration

Parameters

Returns void

OptionalonRenderSettled

See

OptionalonWorkbookChange

Type Declaration

Parameters

Returns void

Remarks

OptionalonWorkbookLoad

Optionalprefetch

Remarks

Default Value

OptionalpropsDocumentError

OptionalpropsDocumentLoading

OptionalpropsDocumentTitle

Remarks

OptionalpropsFormulaBar

OptionalpropsStatusBar

OptionalpropsTaskPaneArea

OptionalpropsToolbar

OptionalpropsWorkbook

Remarks

OptionalrenderDocumentError

Remarks

Default Value

OptionalrenderDocumentLoading

OptionalrenderFormulaBar

OptionalrenderStatusBar

OptionalrenderTaskPaneArea

Param: props

OptionalrenderToolbar

OptionalshowFormulaBar

Default Value

OptionalshowStatusBar

Default Value

Optionalsource

OptionalstartWith

Default Value

Optionalsx

OptionaltaskPaneSide

Default Value

OptionaltemplatePath

Default Value

Optionaltokens

Remarks

OptionaltopLeft

Remarks

OptionaltopRight

OptionalvirtualKeyboard

Default Value

Settings

`Optional`autoFocus

`Optional`confirmOnClose

`Optional`cssBaseline

`Optional`documentTitle

`Optional`editable

`Optional`formulaBarPlacement

`Optional`keyboardGuard

`Optional`licenseKey

`Optional`logo

`Optional`muiTheme

`Optional`onDirtyChange

`Optional`onDocumentError

`Optional`onRenderSettled

`Optional`onWorkbookChange

`Optional`onWorkbookLoad

`Optional`prefetch

`Optional`propsDocumentError

`Optional`propsDocumentLoading

`Optional`propsDocumentTitle

`Optional`propsFormulaBar

`Optional`propsStatusBar

`Optional`propsTaskPaneArea

`Optional`propsToolbar

`Optional`propsWorkbook

`Optional`renderDocumentError

`Optional`renderDocumentLoading

`Optional`renderFormulaBar

`Optional`renderStatusBar

`Optional`renderTaskPaneArea

`Optional`renderToolbar

`Optional`showFormulaBar

`Optional`showStatusBar

`Optional`source

`Optional`startWith

`Optional`sx

`Optional`taskPaneSide

`Optional`templatePath

`Optional`tokens

`Optional`topLeft

`Optional`topRight

`Optional`virtualKeyboard