---
title: File Properties
sidebar_position: 12
---

<details>
  <summary><b>File Format Support</b> (click to show)</summary>

Excel supports a number of standard properties. Most modern versions of Excel
also support custom properties.

| Formats   | Standard | Custom | Separate |
|:----------|:--------:|:-------|----------|
| XLSX/XLSM |     ✔    |    ✔   |     ✔    |
| XLSB      |     ✔    |    ✔   |     ✔    |
| XLML      |     ✔    |    ✔   |     ✔    |
| BIFF8 XLS |     ✔    |    ✔   |          |
| BIFF5 XLS |     R    |    R   |          |

The letter R (R) marks features parsed but not written in the format.

The "Separate" column marks formats that store standard and custom properties
in different locations. Legacy XLS files commingle properties.

</details>

Modern spreadsheet software support special file properties including titles and
keywords. Third-party tools can understand the file properties without having to
process or understand the spreadsheet structure.

In the SheetJS Data Model, the workbook object `Props` property holds standard
properties and the `Custprops` property holds custom properties.

## Live Demo

The following demo generates `SheetJSProperties.xlsx` with two file properties:

- The standard `Title` property will be set to `SheetJS Properties Test`. This
  will be displayed in the "Summary" tab of the Excel file properties dialog:

!["Standard" tab showing "Title" property](pathname:///props/standard-title.png)

- The custom `Custom Quip` property will be set to `Get Sheet Done`. This will
  be displayed in the "Properties" table in the "Custom" tab of the dialog:

!["Custom" tab with "Custom Quip" property](pathname:///props/custom-quip.png)


```jsx live
function SheetJSPropertiesExport() { return (<button onClick={() => {
  /* create workbook */
  var ws = XLSX.utils.aoa_to_sheet([ ["Check Props"] ]);
  var wb = XLSX.utils.book_new(ws);

  /* add Title */
  if(!wb.Props) wb.Props = {};
  wb.Props.Title = "SheetJS Properties Test";

  /* add Custom Quip */
  if(!wb.Custprops) wb.Custprops = {};
  wb.Custprops["Custom Quip"] = "Get Sheet Done";

  /* export to XLSX */
  XLSX.writeFile(wb, "SheetJSProperties.xlsx");
}}><b>Click here to Export</b></button>); }
```

## Spreadsheet Applications

Spreadsheet applications commonly display file properties in separate windows:

- Excel for Windows: select "File" above the ribbon bar, select "Info" in the
  left sidebar, and click Properties > Advanced Properties

- Excel for Mac: select "File" in the menu bar and select "Properties"

- WPS Office: select "Menu" > "Document Encryption" > "Properties"

:::note pass

When this demo was last tested, Apple Numbers (14.2, build 7041.0.109) did not
support file properties in the XLSX import and export codecs.

:::

## Standard Properties

Some properties cannot be changed in spreadsheet applications. The underlying
SheetJS output codecs can write arbitrary values.

The `Props` object understands the "standard" properties listed in the following
table. "SheetJS Name" refers to the name of the property in the `Props` object. 
"Excel Property Setting" refers to the name in the Excel file properties dialog.

| SheetJS Name  | Excel Property Setting         |
|:--------------|:-------------------------------|
| `Title`       | Summary tab "Title"            |
| `Subject`     | Summary tab "Subject"          |
| `Author`      | Summary tab "Author"           |
| `Manager`     | Summary tab "Manager"          |
| `Company`     | Summary tab "Company"          |
| `Category`    | Summary tab "Category"         |
| `Keywords`    | Summary tab "Keywords"         |
| `Comments`    | Summary tab "Comments"         |
| `LastAuthor`  | Statistics tab "Last saved by" |
| `CreatedDate` | Statistics tab "Created"       |

It is strongly recommended to test if the `Props` property exists:

```js title="Set the 'Title' file property"
/* ensure `Props` exists */
if(!wb.Props) wb.Props = {};

/* set `Title` property */
wb.Props.Title = "SheetJS Properties Test";
```

## Custom Properties

Custom properties are added in the workbook `Custprops` object. As with `Props`,
scripts should test for the existence of the `Custprops` property:

```js title="Set the 'Custom Quip' custom file property"
/* ensure `Custprops` exists */
if(!wb.Custprops) wb.Custprops = {};

/* set `Custom Quip` property */
wb.Custprops["Custom Quip"] = "Get Sheet Done";
```

## Export Override

The SheetJS `write` and `writeFile` methods[^2] accept options. The `Props`
option instructs the writer to override properties from the workbook object.

In the following example, the workbook object sets the "Title" and "Keywords"
standard properties. `writeFile` will override the "Keywords" property and add
the "Category" property. The generated file will have the following properties:

- "Title" will be set to "SheetJS Properties Test" (from the workbook object)
- "Keywords" will be blank (overridden by `writeFile` option)
- "Category" will be "Sheetpost"  (assigned through `writeFile` option)


```jsx live
function SheetJSPropertiesOverride() { return (<button onClick={() => {
  /* create workbook */
  var ws = XLSX.utils.aoa_to_sheet([ ["Check Props"] ]);
  var wb = XLSX.utils.book_new(ws);

  /* add Title and Keywords */
  if(!wb.Props) wb.Props = {};
  wb.Props.Title = "SheetJS Properties Test";
  wb.Props.Keywords = "Properties";

  /* export to XLSX with property overrides */
  XLSX.writeFile(wb, "SheetJSPropertiesOverride.xlsx", { Props: {
    Keywords: "",            /* Ensure `Keywords` is blank */
    Category: "Sheetpost",   /* Add `Category` property */
  }});
}}><b>Click here to Export</b></button>); }
```

[^1]: See [`write` and `writeFile` in "Writing Files"](/docs/api/write-options)