SheetXL - v1.0.2
    Preparing search index...

    Interface WorkbookElementProps

    Properties and methods available on the workbook element.

    Every render* slot is mounted as its own component, so a renderer may call hooks. Omit a slot (or pass undefined) for its default; pass null to render nothing.

    interface WorkbookElementProps {
        autoFocus?: boolean | FocusOptions;
        colorScheme?: "auto" | ThemeMode;
        editable?: SheetEditable;
        focusNameBox?: () => void;
        gridColorScheme?: "auto" | ThemeMode;
        onRenderSettled?: (event: WorkbookRenderSettledEvent) => void;
        onWorkbookChange?: (workbook: IWorkbook | null) => void;
        onWorkbookLoad?: (event: WorkbookLoadEvent) => void | Promise<void>;
        prefetch?: boolean | "auto";
        propsContextMenu?: Partial<WorkbookMenuRenderProps>;
        propsFloatPanel?: Partial<FloatPanelProps>;
        propsSheet?: Partial<WorksheetElementProps>;
        propsTabs?: Partial<WorkbookStripProps>;
        propsWorkbookLoading?: Partial<LoadingPanelProps>;
        ref?: Ref<IWorkbookElement>;
        renderColumnMenu?: RenderSlotFn<ColumnMenuRenderProps> | null;
        renderContextMenu?: RenderSlotFn<ContextMenuRenderProps> | null;
        renderFillMenu?: RenderSlotFn<FillMenuRenderProps> | null;
        renderFloatPanel?: RenderFloatPanel;
        renderMovableMenu?: RenderSlotFn<MovableMenuRenderProps> | null;
        renderOpaqueSheet?: RenderSlotFn<OpaqueSheetElementProps>;
        renderPivotMenu?: RenderSlotFn<PivotMenuRenderProps> | null;
        renderSettleTimeout?: number;
        renderTabs?: RenderSlotFn<WorkbookStripProps> | null;
        renderWorkbookError?: RenderSlotFn<ErrorPanelProps> | null;
        renderWorkbookLoading?: RenderSlotFn<LoadingPanelProps> | null;
        renderWorksheet?: RenderSlotFn<WorksheetElementProps>;
        showHorizontalScrollbar?: boolean;
        showTabs?: boolean;
        showVerticalScrollbar?: boolean;
        tokens?: Partial<
            Record<
                ThemeMode,
                Partial<Record<ExplicitSurface, Partial<TokenTheme>>>,
            >,
        >;
        undoManager?: UndoManager;
        workbook?: IWorkbook | Promise<IWorkbook> | ReadOptions;
        wrapperMain?: (children: ReactNode) => ReactElement;
    }

    Hierarchy

    • Omit<React.HTMLAttributes<HTMLDivElement>, "autoFocus">
    • Attributes
      • WorkbookElementProps
    Index
    autoFocus? colorScheme? editable? focusNameBox? gridColorScheme? onRenderSettled? onWorkbookChange? onWorkbookLoad? prefetch? propsContextMenu? propsFloatPanel? propsSheet? propsTabs? propsWorkbookLoading? ref? renderColumnMenu? renderContextMenu? renderFillMenu? renderFloatPanel? renderMovableMenu? renderOpaqueSheet? renderPivotMenu? renderSettleTimeout? renderTabs? renderWorkbookError? renderWorkbookLoading? renderWorksheet? showHorizontalScrollbar? showTabs? showVerticalScrollbar? tokens? undoManager? workbook? wrapperMain?
    autoFocus?: boolean | FocusOptions

    Will autofocus to the sheet.

    false
    colorScheme?: "auto" | ThemeMode

    Controlled override for the app (chrome) light/dark scheme. 'auto' follows the page: a dark/light class on <html>/<body>, else the OS.

    When omitted, the workbook self-sources it from the shared appearance preference (ThemeStateKey.Mode). With no preference set it is light, unless the page puts a dark/light class on <html>/<body> or a ThemeModeFallbackContext above says otherwise.

    editable?: SheetEditable

    The app-created editor for the new always-mounted cell editor. Pass the SAME stable IEditable instance here and to the formula bar for free two-way sync; this forwards it to the sheet's editor layer.

    focusNameBox?: () => void

    Focus the formula-bar name box (Alt+F3 / activeNameBox) — a bridge from a host shell (e.g. studio) to the workbook-ops command, until the name box has a react home. Wired into the per-workbook command scope's workbook commands.

    gridColorScheme?: "auto" | ThemeMode

    Controlled override for the grid-body scheme. 'auto' follows the page as colorScheme does.

    When omitted, the grid follows colorScheme only if Enable Dark Grid (ThemeStateKey.DarkGrid) is on, so by default it stays light in a dark app. Pass it to make the grid dark with the page.

    onRenderSettled?: (event: WorkbookRenderSettledEvent) => void

    Called once the first screen has finished drawing (pictures, charts, the sheet background) and painted, or once WorkbookElementProps.renderSettleTimeout runs out. The workbook shows at this moment, so it opens whole rather than filling in piece by piece.

    Fires once, after WorkbookElementProps.onWorkbookLoad (and after a returned promise resolves).

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

    Called with the workbook once WorkbookElementProps.workbook resolves, and again whenever a new input resolves to a different one. Until the first input resolves, or if an input fails, the workbook is null; while a later input resolves, the current workbook is kept.

    Lets an app pass a Promise here and hold the live workbook in its own state, without awaiting or suspending.

    const [pending] = useState(() => createInvoice());
    const [workbook, setWorkbook] = useState<IWorkbook | null>(null);
    const [total] = useCellValue<number>(workbook, 'D23');
    return <WorkbookElement workbook={pending} onWorkbookChange={setWorkbook} />;
    onWorkbookLoad?: (event: WorkbookLoadEvent) => void | Promise<void>

    Called when the workbook first renders, before its pictures and charts have finished drawing. To reveal it, use WorkbookElementProps.onRenderSettled.

    prefetch?: boolean | "auto"

    Whether features that load on first use (charts, shapes, form controls, file formats, dialogs) are loaded ahead of use once the workbook has shown, so their first use does not wait on the network.

    • 'auto' - only while the browser reports a fast connection. Browsers that report none (Firefox, Safari) load each feature on first use.
    • true - on any connection but a 2g one.
    • false - each feature on first use.

    Loads every module defined with defineLazyModule from @sheetxl/utils that has not opted out, including every kind registered with MovableContentRegistry and registerMovableRenderer. Nothing is loaded while offline or when the connection asks to save data; it resumes when the connection changes.

    'auto'
    propsContextMenu?: Partial<WorkbookMenuRenderProps>

    Props handed to every menu renderer.

    propsFloatPanel?: Partial<FloatPanelProps>

    Allow for customizations on the floating surface used for the workbook's popups.

    propsSheet?: Partial<WorksheetElementProps>

    Allow for customizations on the sheet.

    propsTabs?: Partial<WorkbookStripProps>

    Allow for customizations on tabs.

    propsWorkbookLoading?: Partial<LoadingPanelProps>

    Allow for customizations on loading panels.

    ref?: Ref<IWorkbookElement>

    Ref for the workbook element.

    renderColumnMenu?: RenderSlotFn<ColumnMenuRenderProps> | null

    Render the filter menu of a table column's button. The default renders none.

    renderContextMenu?: RenderSlotFn<ContextMenuRenderProps> | null

    Render the grid's context menu. The default renders none, and the browser's menu shows.

    renderFillMenu?: RenderSlotFn<FillMenuRenderProps> | null

    Render the menu a right-drag of the fill handle ends in. The default renders none, and the right-drag is inert.

    renderFloatPanel?: RenderFloatPanel

    Render the floating surface used for the workbook's own popups (e.g. context menus). Defaults to the neutral FloatPanel; UI layers inject a themed surface (e.g. MUI Paper).

    renderMovableMenu?: RenderSlotFn<MovableMenuRenderProps> | null

    Render the context menu of a chart, shape or other movable. The default renders none.

    renderOpaqueSheet?: RenderSlotFn<OpaqueSheetElementProps>

    Render the pane of a chart sheet, a macro sheet or a dialog sheet while it is the active tab.

    renderPivotMenu?: RenderSlotFn<PivotMenuRenderProps> | null

    Render the menu of a pivot table's field button: its items to show or hide, or a page field's item to choose. The default renders none.

    renderSettleTimeout?: number

    How long, in milliseconds after the first paint, the workbook stays hidden waiting for the first screen to finish drawing. Whatever is still loading then appears when it is ready. 0 shows the workbook at its first paint; Infinity waits for everything.

    300
    renderTabs?: RenderSlotFn<WorkbookStripProps> | null

    Render the sheet tabs.

    renderWorkbookError?: RenderSlotFn<ErrorPanelProps> | null

    Custom error panel, shown when a Promise / IWorkbookIO.ReadOptions WorkbookElementProps.workbook fails to resolve. Defaults to a minimal message. (Studio supplies a themed panel.)

    renderWorkbookLoading?: RenderSlotFn<LoadingPanelProps> | null

    Assign a custom loading panel.

    renderWorksheet?: RenderSlotFn<WorksheetElementProps>

    Render the active worksheet. Pass props.ref on to the IWorksheetElement.

    showHorizontalScrollbar?: boolean

    Show the horizontal scrollbar.

    showTabs?: boolean

    This doesn't influence # of tabs just the visibility of the widget.

    'workbook model but can be overridden'
    showVerticalScrollbar?: boolean

    Show the vertical scrollbar.

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

    Token values for this workbook, per mode and surface: the React form of a stylesheet in @layer sxl-overrides, scoped to this instance.

    <WorkbookElement
      colorScheme="auto"
      gridColorScheme="auto"
      tokens={{
        dark: {
          app: { 'color-base-100': '#14102c', 'color-base-200': '#14102c', 'color-primary': '#6e9bff' },
          header: { 'color-base-100': '#1a1538', 'color-base-300': '#312b55' }
        }
      }}
    />

    An app value reaches the grid and headers too in that mode; state a grid or header cell to make that surface differ. Pass a stable object: a new reference rebuilds the stylesheet.

    undoManager?: UndoManager

    A custom undo manager.

    A TransactionUndoManager bound to the workbook's transaction store.

    workbook?: IWorkbook | Promise<IWorkbook> | ReadOptions

    The workbook to render: a live IWorkbook, a Promise for one, or IWorkbookIO.ReadOptions to read one from a source. If omitted (or an empty object), a default workbook is created. A promise / read-options input shows the loading panel while resolving and the error panel (WorkbookElementProps.renderWorkbookError) on failure.

    This can be accessed (once resolved) via the workbook ref.

    wrapperMain?: (children: ReactNode) => ReactElement

    Allows users to Wrap stage children in Top level Context.

    Settings
    Member Visibility

    On This Page
    Properties