wb_freeze_pane: Freeze panes of a worksheet

In openxlsx2: Read, Write and Edit 'xlsx' Files

Freeze panes of a worksheet

Description

The wb_freeze_pane() function locks a specific area of a worksheet to keep rows or columns visible while scrolling through other parts of the data. This is achieved by defining a "split" point, where all content above or to the left of the designated active region remains fixed.

Usage

wb_freeze_pane(
  wb,
  sheet = current_sheet(),
  first_active_row = NULL,
  first_active_col = NULL,
  first_row = FALSE,
  first_col = FALSE,
  ...
)

Arguments

wb	A wbWorkbook object.
sheet	The name or index of the worksheet to modify. Defaults to the current sheet.
first_active_row	The index of the first row that should remain scrollable. Rows above this will be frozen.
first_active_col	The index or character label of the first column that should remain scrollable. Columns to the left will be frozen.
first_row	Logical; if TRUE, freezes the first row of the worksheet.
first_col	Logical; if TRUE, freezes the first column of the worksheet.
...	Additional arguments for internal case standardization.

Details

The function operates by calculating xSplit and ySplit values based on the provided active region coordinates. The first_active_row and first_active_col parameters define the first cell that remains scrollable; consequently, the frozen area consists of all rows and columns preceding these indices.

For common use cases, the first_row and first_col logical flags provide optimized shortcuts. Enabling first_row locks the top row (equivalent to setting the active region at row 2), while first_col locks the leftmost column (equivalent to setting the active region at column 2). If both are enabled, the function automatically freezes the intersection at cell "B2".

The internal logic translates these coordinates into a ⁠<pane />⁠ XML node, which specifies the topLeftCell of the scrollable region and assigns the activePane (e.g., "bottomLeft", "topRight", or "bottomRight") to ensure correct cursor behavior within the spreadsheet software.

Notes

• If first_active_row and first_active_col are both set to 1, or if all arguments are omitted, the function returns the workbook unchanged as there is no region to freeze.

• This function overwrites any existing pane configuration for the specified worksheet.

See Also

Other workbook wrappers: base_font-wb, col_widths-wb, creators-wb, grouping-wb, row_heights-wb, wb_add_chartsheet(), wb_add_data(), wb_add_data_table(), wb_add_formula(), wb_add_hyperlink(), wb_add_pivot_table(), wb_add_slicer(), wb_add_worksheet(), wb_base_colors, wb_clone_worksheet(), wb_copy_cells(), wb_merge_cells(), wb_save(), wb_set_last_modified_by(), wb_workbook()

Other worksheet content functions: col_widths-wb, filter-wb, grouping-wb, named_region-wb, row_heights-wb, wb_add_conditional_formatting(), wb_add_data(), wb_add_data_table(), wb_add_formula(), wb_add_hyperlink(), wb_add_pivot_table(), wb_add_slicer(), wb_add_thread(), wb_merge_cells()

Examples

wb <- wb_workbook()
## Add some worksheets
wb$add_worksheet("Sheet 1")
wb$add_worksheet("Sheet 2")
wb$add_worksheet("Sheet 3")
wb$add_worksheet("Sheet 4")

## Freeze Panes
wb$freeze_pane("Sheet 1", first_active_row = 5, first_active_col = 3)
wb$freeze_pane("Sheet 2", first_col = TRUE) ## shortcut to first_active_col = 2
wb$freeze_pane(3, first_row = TRUE) ## shortcut to first_active_row = 2
wb$freeze_pane(4, first_active_row = 1, first_active_col = "D")

openxlsx2 documentation built on Feb. 21, 2026, 9:07 a.m.