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;
    manageVisualViewport?: boolean;
    muiTheme?: ThemeOptions;
    onDirtyChange?: (isDirty: boolean) => void;
    onDocumentError?: (error: any) => void;
    onWorkbookChange?: (workbook: IWorkbook | null) => void;
    onWorkbookLoad?: (event: WorkbookLoadEvent) => void | Promise<void>;
    prefetch?: "all" | "none" | "common";
    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?: (props: ErrorPanelProps) => ReactElement;
    renderDocumentLoading?: (props: LoadingPanelProps) => ReactElement;
    renderFormulaBar?: (props: FormulaBarProps) => ReactElement;
    renderStatusBar?: (props: StatusBarProps) => ReactElement;
    renderTaskPaneArea?: (
        props: TaskPaneAreaProps,
    ) => ReactElement<ITaskPaneAreaElement>;
    renderToolbar?: (props: WorkbookToolbarsProps) => ReactElement;
    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;
}

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`manageVisualViewport

manageVisualViewport?: boolean

Whether the studio sizes itself to the visual viewport while the formula bar is at the bottom, so the bar stays above the virtual keyboard.

Default Value

true

Remarks

iOS Safari does not shrink the page for the keyboard; it scrolls the focused field into view instead. The studio undoes that: it takes the visual viewport's height, pins itself to the visual viewport's offset and scrolls the page back to the top after each keyboard change. A host page that already manages the keyboard turns this off. Ignored while the bar is at the top.

`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. A wrapping TokenThemeProvider layers token overrides 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`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?: "all" | "none" | "common"

Which features to load ahead of use, once the studio is showing.

none - load each feature when it is first used.
common - features used in most sessions.
all - every feature.

Remarks

Nothing is loaded ahead of use while offline or when the connection asks to save data, and only common features on a slow connection. The script editor and its compiler are always loaded on first use.

Default Value

'common'

`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?: (props: ErrorPanelProps) => ReactElement

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?: (props: LoadingPanelProps) => ReactElement

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

`Optional`renderFormulaBar

renderFormulaBar?: (props: FormulaBarProps) => ReactElement

Render a custom formula bar (replaces the default).

`Optional`renderStatusBar

renderStatusBar?: (props: StatusBarProps) => ReactElement

Render a custom status bar (replaces the default).

`Optional`renderTaskPaneArea

renderTaskPaneArea?: (
props: TaskPaneAreaProps,
) => ReactElement<ITaskPaneAreaElement>

Render TaskPaneArea.

Type Declaration

- (props: TaskPaneAreaProps): ReactElement<ITaskPaneAreaElement>
- Parameters
  - props: TaskPaneAreaProps
    The properties for the TaskPaneArea.
  Returns ReactElement<ITaskPaneAreaElement>
  A React Element representing the TaskPaneArea.

`Optional`renderToolbar

renderToolbar?: (props: WorkbookToolbarsProps) => ReactElement

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, 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. A wrapping TokenThemeProvider remains the right doorway for a client brand override, but it emits into sxl-overrides, which — being a higher layer — applies across every surface at once.

`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.

Interface StudioAppOptions

Hierarchy

Index

Properties

Properties

OptionalautoFocus

Default Value

OptionalconfirmOnClose

OptionalcssBaseline

Default Value

OptionaldocumentTitle

Optionaleditable

OptionalformulaBarPlacement

Default Value

Remarks

OptionalkeyboardGuard

OptionallicenseKey

Remarks

Optionallogo

OptionalmanageVisualViewport

Default Value

Remarks

OptionalmuiTheme

Remarks

OptionalonDirtyChange

Type Declaration

Parameters

Returns void

Remarks

OptionalonDocumentError

Type Declaration

Parameters

Returns void

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

Type Declaration

Parameters

Returns ReactElement<ITaskPaneAreaElement>

OptionalrenderToolbar

OptionalshowFormulaBar

Default Value

OptionalshowStatusBar

Default Value

Optionalsource

OptionalstartWith

Default Value

Optionalsx

OptionaltaskPaneSide

Default Value

OptionaltemplatePath

Default Value

Optionaltokens

Remarks

OptionaltopLeft

Remarks

OptionaltopRight

`Optional`autoFocus

`Optional`confirmOnClose

`Optional`cssBaseline

`Optional`documentTitle

`Optional`editable

`Optional`formulaBarPlacement

`Optional`keyboardGuard

`Optional`licenseKey

`Optional`logo

`Optional`manageVisualViewport

`Optional`muiTheme

`Optional`onDirtyChange

`Optional`onDocumentError

`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