XLSX

Protection

Lock worksheets and workbooks, define protected ranges, and share files with passwords

Sheet Protection

Protect a worksheet with a password and restrict user actions. When a plaintext password is provided, the legacy XOR hash and modern SHA-512 hash are both computed automatically.

{
  "worksheets": [
    {
      "name": "Protected",
      "rows": [
        { "cells": [{ "value": "Quarter" }, { "value": "2023" }, { "value": "2024" }] },
        { "cells": [{ "value": "Q1" }, { "value": 100 }, { "value": 120 }] },
        { "cells": [{ "value": "Q2" }, { "value": 150 }, { "value": 170 }] }
      ],
      "protection": {
        "sheet": true,
        "password": "secret",
        "formatCells": false,
        "insertRows": false,
        "sort": false
      }
    }
  ]
}

import { generateWorkbook } from "@office-open/xlsx";

await generateWorkbook({
  worksheets: [
    {
      name: "Protected",
      rows: [
        { cells: [{ value: "Quarter" }, { value: "2023" }, { value: "2024" }] },
        { cells: [{ value: "Q1" }, { value: 100 }, { value: 120 }] },
        { cells: [{ value: "Q2" }, { value: 150 }, { value: 170 }] },
      ],
      protection: {
        sheet: true,
        password: "secret",
        formatCells: false,
        insertRows: false,
        sort: false,
      },
    },
  ],
});

Sheet Protection Options

Option	Type	Description
`sheet`	`boolean`	Enable sheet protection
`password`	`string`	Plaintext password (auto-hashed)
`objects`	`boolean`	Protect objects
`scenarios`	`boolean`	Protect scenarios
`formatCells`	`boolean`	Allow formatting cells
`formatColumns`	`boolean`	Allow formatting columns
`formatRows`	`boolean`	Allow formatting rows
`insertColumns`	`boolean`	Allow inserting columns
`insertRows`	`boolean`	Allow inserting rows
`insertHyperlinks`	`boolean`	Allow inserting hyperlinks
`deleteColumns`	`boolean`	Allow deleting columns
`deleteRows`	`boolean`	Allow deleting rows
`selectLockedCells`	`boolean`	Allow selecting locked cells
`sort`	`boolean`	Allow sorting
`autoFilter`	`boolean`	Allow auto filter
`pivotTables`	`boolean`	Allow pivot tables
`selectUnlockedCells`	`boolean`	Allow selecting unlocked cells

When password is provided, both a legacy XOR hash (for compatibility) and a modern SHA-512 hash with random salt and 100,000 iterations are generated automatically. You can also provide pre-computed values directly:

{
  "protection": {
    "sheet": true,
    "algorithmName": "SHA-512",
    "hashValue": "base64hash...",
    "saltValue": "base64salt...",
    "spinCount": 100000
  }
}

Option	Type	Description
`algorithmName`	`string`	Hash algorithm (e.g. `"SHA-512"`)
`hashValue`	`string`	Base64-encoded password hash
`saltValue`	`string`	Base64-encoded salt
`spinCount`	`number`	Number of hash iterations

Protected Ranges

Define named ranges within a protected sheet that specific users can edit:

{
  "worksheets": [
    {
      "name": "Protected",
      "rows": [
        { "cells": [{ "value": "Quarter" }, { "value": "2023" }, { "value": "2024" }] },
        { "cells": [{ "value": "Q1" }, { "value": 100 }, { "value": 120 }] },
        { "cells": [{ "value": "Q2" }, { "value": 150 }, { "value": 170 }] }
      ],
      "protection": {
        "sheet": true,
        "password": "secret"
      },
      "protectedRanges": [{ "name": "EditableRange", "sqref": "B2:C5", "password": "range1" }]
    }
  ]
}

import { generateWorkbook } from "@office-open/xlsx";

await generateWorkbook({
  worksheets: [
    {
      name: "Protected",
      rows: [
        { cells: [{ value: "Quarter" }, { value: "2023" }, { value: "2024" }] },
        { cells: [{ value: "Q1" }, { value: 100 }, { value: 120 }] },
        { cells: [{ value: "Q2" }, { value: 150 }, { value: 170 }] },
      ],
      protection: {
        sheet: true,
        password: "secret",
      },
      protectedRanges: [{ name: "EditableRange", sqref: "B2:C5", password: "range1" }],
    },
  ],
});

Protected Range Options

Option	Type	Description
`name`	`string`	Range name (required)
`sqref`	`string`	Cell range reference, e.g. `"B2:C5"` (required)
`password`	`string`	Plaintext password (auto-hashed)
`algorithmName`	`string`	Hash algorithm for modern encryption
`hashValue`	`string`	Base64-encoded password hash
`saltValue`	`string`	Base64-encoded salt
`spinCount`	`number`	Number of hash iterations
`securityDescriptor`	`string`	SID security descriptor string

Workbook Protection

Lock workbook structure and windows at the workbook level. Supports separate passwords for structure and revisions:

{
  "workbookProtection": {
    "lockStructure": true,
    "lockWindows": true,
    "workbookPassword": "admin"
  },
  "worksheets": [
    {
      "name": "Data",
      "rows": [{ "cells": [{ "value": "Protected workbook" }] }]
    }
  ]
}

import { generateWorkbook } from "@office-open/xlsx";

await generateWorkbook({
  workbookProtection: {
    lockStructure: true,
    lockWindows: true,
    workbookPassword: "admin",
  },
  worksheets: [{ name: "Data", rows: [{ cells: [{ value: "Protected workbook" }] }] }],
});

Workbook Protection Options

Option	Type	Description
`lockStructure`	`boolean`	Lock workbook structure (add/delete/rename sheets)
`lockWindows`	`boolean`	Lock workbook windows
`lockRevision`	`boolean`	Lock revisions
`workbookPassword`	`string`	Plaintext structure password (auto-hashed)
`revisionsPassword`	`string`	Plaintext revisions password (auto-hashed)

Both passwords also support modern encryption options: workbookAlgorithmName, workbookHashValue, workbookSaltValue, workbookSpinCount and revisionsAlgorithmName, revisionsHashValue, revisionsSaltValue, revisionsSpinCount.

Recommend read-only mode and record who has the file open:

{
  "fileSharing": {
    "readOnlyRecommended": true,
    "userName": "John"
  },
  "worksheets": [
    {
      "name": "Data",
      "rows": [{ "cells": [{ "value": "Shared file" }] }]
    }
  ]
}

import { generateWorkbook } from "@office-open/xlsx";

await generateWorkbook({
  fileSharing: {
    readOnlyRecommended: true,
    userName: "John",
  },
  worksheets: [{ name: "Data", rows: [{ cells: [{ value: "Shared file" }] }] }],
});

Option	Type	Description
`readOnlyRecommended`	`boolean`	Recommend read-only mode
`userName`	`string`	User name who has the file locked
`reservationPassword`	`string`	Plaintext reservation password (auto-hashed)
`algorithmName`	`string`	Hash algorithm for modern encryption
`hashValue`	`string`	Base64-encoded password hash
`saltValue`	`string`	Base64-encoded salt
`spinCount`	`number`	Number of hash iterations

Edit this pageorReport an issue

Comments

Add comments and notes to cells

Shared Workbook Revisions

Track changes in shared workbooks via the revision log (revisionHeaders, revisions, users)