Setting Options

DataGridXL does not require a long list of options. You can create a fully functional grid by just passing data.

However, you may wish to change some or all of your grid's default settings.

Default user actions

By default, all user actions are enabled and allowed. These are all user actions that can be disallowed:

Row Actions

• allowDeleteRows
• allowInsertRows
• allowMoveRows
• allowHideRows
• allowShowRows
• allowFreezeRows

Column Actions

• allowDeleteCols
• allowInsertCols
• allowMoveCols
• allowHideCols
• allowShowCols
• allowFreezeCols
• allowResizeCols

Cell Actions

• allowEditCells
• allowFillCells

Clipboard Actions

• allowCopy
• allowCut
• allowPaste

To disallow any of these user actions, set them to false in your DataGridXL options object:

const grid = new DataGridXL("grid", {
    data: [/*...*/],
    allowResizeCols: false,
    allowFillCells: false
});

By disallowing a user action, the corresponding mouse and touch drag-actions become disabled and any related items are excluded from the Context Menu.

Any related keyboard listeners are de-activated as well. (Meaning that CTRL+V and CMD+V won't work when allowPaste is set to false).

Headers and Labels

Row headers

A default grid will display plain center-aligned "numbers" row header labels (1, 2, 3...). By setting a few simple options, you can align the row labels to the left and add a prefix as well.

const grid = new DataGridXL("grid", {
  data: [/*...*/],
  rowHeaderLabelAlign: "left",
  rowHeaderLabelPrefix: "Item #"
});

With these settings, row headers will neatly display "Item #1", "Item #2", "Item #3", etc.

Column headers

If your data array is a JSON-style array of objects, your object field names will automatically serve as column header labels.

If you use a 2D array, your columns are untitled. In case of untitled columns, "letters" (A, B, C...) will be used as header labels.

By default, row headers are set to "numbers" and column headers are set to "letters". This means that any data grid displaying (untitled) 2D-array data will default to showing spreadsheet-like header labels (123 for rows, ABC for columns).

Numbers as Column Headers

You might want to change these default settings, as DataGridXL does not include Excel-like formulas. Seeing those spreadsheet-style headers, your user might type something like "=B1+B2" only to be confused to see their raw formula end up as the rendered cell value.

To avoid confusion, use "numbers" for your column headers, same like row headers. You can choose to use a prefix as well.

const grid = new DataGridXL("grid", {
  data: [/*...*/],
  rowHeaderWidth: 120,
  rowHeaderLabelAlign: "left",
  rowHeaderLabelPrefix: "Row ",
  colHeaderLabelType: "numbers",
  colHeaderLabelAlign: "left",
  colHeaderLabelPrefix: "Col "
});

Column Options

You can also use the columns option to assign titles to unnamed columns, or rename existing columns. We've demonstrated this in the Passing Data article.

Not only can you re-name or re-order columns, you also give them unique widths and set their alignment:

const grid = new DataGridXL("grid", {
  data: [
    ["Kooikerhondje", 210, "The Netherlands"],
    ["Beagle", 235, "Great Britain"],
    ["Dalmatian", 90, "Croatia"]
  ],
  columns: [{
    width: 200,
    align: "right",
    title: "Country",
    source: 2
  }, {
    width: 140,
    align: "center",
    title: "Dog Breed",
    source: 0
  }]
});

Style

You might have noticed that you don't need to include a CSS file along with the DataGridXL JavaScript file. Changing the grid's colors is done via the theme setting, which takes a plain JavaScript object.

const my_theme = {
  "selector"                  : "#15202b",
  "header"                    : "#ffffff",
  "header_text"               : "#44ffaa"
};

const grid = new DataGridXL("grid", {
  data: [/*...*/],
  theme: my_theme
});

There are many more style settings. Our docs has an entire page dedicated to DataGridXL themes.

Changing options

If you are accustomed to working with reactive frameworks like Angular, React or Vue, be aware that DataGridXL options are not reactive.

// Avoid changing options like this:
grid.allowFillCells = false;

The best option to change options after grid initialization, is to create a new grid with a fresh set of options. Target the same container id and your old grid will be replaced:

// create grid (1st time)
const initialOptions = {
  data: DataGridXL.createDummyData(5,5)
};

var grid = new DataGridXL("grid", initialOptions);

someButton.onclick = function(){

  // create a new grid with new options
  // just overwrite grid variable
  const newOptions = {
    data: DataGridXL.createDummyData(10,5),
    rowHeight: 40
  };

  grid = new DataGridXL("grid", newOptions);

};

Further reading

Now that you know how to change default options, we think you're ready to create a mini app. Follow us to the next chapter: DataGridXL methods.