Options

WebPivotTable uses options internally to control its look and feel and behaviour. Changing any option triggers WebPivotTable to refresh and the change takes effect immediately.

Setting these options is the primary mechanism to customise WebPivotTable.

How To Set Options?

There are two ways to set options:

• Passing options as an attribute of the web-pivot-table tag

  <web-pivot-table
    options='{"localeFilePath": "./locales/", "locale":"en", "leavePageWarning": 0}'>
  </web-pivot-table>

Since an attribute of an HTML tag or custom element can only be a string, we need to stringify options when passing them this way. WebPivotTable will convert this string to a JavaScript object and deeply merge it into the default options.

It is easy to make mistakes when writing options as a JSON string, so this approach works best for a small number of simple values. When using WebPivotTable together with a JavaScript framework such as React or Vue, you can pass a JavaScript object directly as a prop, making complex options easy to manage.

• Calling the setOptions method

  After the <web-pivot-table> element is created on the page, you can call setOptions directly on the element:

    const wpt = document.querySelector('web-pivot-table');
  
    wpt.setOptions({
      localeFilePath: "./locales/",
      locale: "en",
      leavePageWarning: 0,
    });
  

  Because you pass a plain JavaScript object that is deeply merged into the default options, this is the preferred way to set complex or nested options.

  See [APIs](/doc/apis) for the full list of available methods.

`leavePageWarning`

If enabled, the browser shows a confirmation dialog giving end users a chance to save their work before leaving. The dialog is a native browser dialog and may look different across browsers.

`locale`

`localeFilePath`

`localeDeploymentMode`

`localeBaseUrl`

`localeCdnBaseUrl`

`availableLocales`

Default availableLocales:

[
  { value: 'en',    abbr: 'EN', label: 'Lbl_English',    attach: ' ( english ) ' },
  { value: 'zh-CN', abbr: 'CN', label: 'Lbl_Chinese',    attach: ' ( 中文 ) ' },
  { value: 'de',    abbr: 'DE', label: 'Lbl_German',     attach: ' ( deutsch ) ' },
  { value: 'tr-TR', abbr: 'TR', label: 'Lbl_Turkish',    attach: ' ( türk ) ' },
  { value: 'es',    abbr: 'ES', label: 'Lbl_Spanish',    attach: ' ( español ) ' },
  { value: 'pt',    abbr: 'PT', label: 'Lbl_Portuguese', attach: ' ( português ) ' },
  { value: 'it',    abbr: 'IT', label: 'Lbl_Italian',    attach: ' ( italiano ) ' },
]

Additional locales (French, Arabic, Russian, Dutch, Greek, Hebrew, Hindi, Hungarian, Swedish, Korean, Japanese, Vietnamese) are defined but commented out by default. Uncomment them in your options to enable.

Please reference Internationalization for more details.

`server`

See Cross-Domain Access for details on how the proxy works and how to deploy your own proxy server.

`limit`

Responsive Breakpoints

Number Formatting

`defaultValueFormat`

Interaction Options

`uiFlags`

UI flags control the visibility of various interface elements. Set any flag to 0 to hide the corresponding feature.

`controlPanel`

The control panel houses the Rows, Columns, Filters, and Values field areas used to build the pivot table.

`styles`

`fileLinks`

Each entry is an object with type, url, and label:

{ type: Constants.sourceType.CSV, url: 'https://cdn.webpivottable.com/samples/example.csv', label: 'USA Selection Poll Data' }

Default links include a variety of CSV, Excel (.xls / .xlsx), WPT, Google Sheets, Web Service, and OLAP sample files hosted at cdn.webpivottable.com/samples/.

You can override this array to supply your own sample files:

wpt.setOptions({
  fileLinks: [
    { type: 'csv',   url: '/data/sales.csv',       label: 'Sales Data' },
    { type: 'excel', url: '/data/inventory.xlsx',   label: 'Inventory Data' },
  ],
});

`customHandlers`

Setting a custom handler to 1 tells WebPivotTable to fire a DOM event instead of performing the default behaviour. You then listen for the event and implement your own logic:

const wpt = document.querySelector('web-pivot-table');

// Enable custom save handler
wpt.setOptions({
  customHandlers: { saveWpt: 1 },
});

// Listen for the save event
wpt.addEventListener('SAVE_WPT', (e) => {
  const wptData = e.detail;
  // Save wptData to your backend
  fetch('/api/save', {
    method: 'POST',
    body: JSON.stringify(wptData),
  });
});

See Events for the full list of events.

`filestack`

`layout`

`fullscreen`

Sheet Options

Each sheet created within WebPivotTable uses the following default display options. These are not set via setOptions but are the defaults applied when a new sheet is created.

Display

Grid

Grid cell styles can be customised per cell type via grid.cellStyle:

grid: {
  cellStyle: {
    columnHeader:   { textAlign: 'center', backgroundColor: '#bfd6eb', fontWeight: 'bold' },
    compoundColumn: { verticalAlign: 'top', textAlign: 'left', backgroundColor: '#bfd6eb', fontWeight: 'bold' },
    rowHeader:      { textAlign: 'left', backgroundColor: '#bfd6eb', fontWeight: 'bold' },
    compoundRow:    { verticalAlign: 'top', textAlign: 'left', backgroundColor: '#bfd6eb', fontWeight: 'bold' },
    totalCell:      { textAlign: 'right', backgroundColor: '#72d2df' },
    subtotalCell:   { textAlign: 'right', backgroundColor: '#d2e9e9' },
    dataCell:       { textAlign: 'right', backgroundColor: '#eee' },
    noDataCell:     { backgroundColor: '#ddd' },
  },
}

Chart

See the Highcharts documentation for the full list of chart options supported under chart.high.