Datatable

lightning-datatable displays tabular data where each column renders the content based on the data type. For example, an email address is displayed as a hyperlink with the mailto: URL scheme by specifying the email type. The default data type on a column is text.

This component implements styling from the data tables blueprint in the Salesforce Lightning Design System.

lightning-datatable is not supported on mobile devices. Supported features include:

• Displaying and formatting of columns with appropriate data types
• Infinite scrolling of rows
• Inline editing for some data types
• Header actions
• Header wrapping
• Row-level actions
• Resizing of columns
• Selecting of rows
• Sorting of columns by ascending and descending order
• Text wrapping and clipping
• Row numbering column
• Cell content alignment
• Appending an SLDS icon to column data
• Hiding the table header
• Hiding the table borders

Tables can be populated during initialization using the data, columns, and key-field attributes. The key-field attribute is required for correct table behavior. It associates each row with a unique identifier. The value you use for key-field is case-sensitive and must match what's in your data array. If you use key-field="Id", make sure the Id you provide in the data array uses Id and not id.

This example creates a table whose first column displays a checkbox for row selection. This column is displayed by default, and you can hide it by adding hide-checkbox-column in your markup. Selecting the checkbox selects the entire row of data and triggers the onrowselection event handler.

1<template>
2    <lightning-datatable
3        data={data}
4        columns={columns}
5        key-field="Id"
6        onrowselection={getSelectedName}
7    >
8    </lightning-datatable>
9</template>

Here's the JavaScript that creates selectable rows and the columns object to their corresponding column data. The Probability column displays percentages with an icon that denotes the increasing or decreasing confidence trend.

This example defines five columns by setting properties and attributes for the columns object. The Probability column displays percentages and an icon that denotes the increasing or decreasing confidence trend. The icon is specified with the cellAttributes property. See Working with Column Properties for more information about the properties for columns.

The JavaScript also loads two rows of data in the table. The Id for each table row is used as the key-field.

1import { LightningElement } from "lwc";
2
3const columns = [
4  { label: "Opportunity name", fieldName: "OpportunityName", type: "text" },
5  {
6    label: "Probability",
7    fieldName: "Probability",
8    type: "percent",
9    cellAttributes: {
10      iconName: { fieldName: "TrendIcon" },
11      iconPosition: "right",
12    },
13  },
14  {
15    label: "Amount",
16    fieldName: "Amount",
17    type: "currency",
18    typeAttributes: { currencyCode: "EUR", step: "0.001" },
19  },
20  { label: "Contact Email", fieldName: "Contact", type: "email" },
21  { label: "Contact Phone", fieldName: "Phone", type: "phone" },
22];
23
24const data = [
25  {
26    Id: "a",
27    OpportunityName: "Cloudhub",
28    Probability: 0.2,
29    Amount: 25000,
30    Contact: "jrogers@cloudhub.com",
31    Phone: "2352235235",
32    TrendIcon: "utility:down",
33  },
34  {
35    Id: "b",
36    OpportunityName: "Quip",
37    Probability: 0.78,
38    Amount: 740000,
39    Contact: "quipy@quip.com",
40    Phone: "2352235235",
41    TrendIcon: "utility:up",
42  },
43];
44
45export default class DatatableExample extends LightningElement {
46  data = data;
47  columns = columns;
48
49  getSelectedName(event) {
50    const selectedRows = event.detail.selectedRows;
51    // Display that fieldName of the selected rows
52    for (let i = 0; i < selectedRows.length; i++) {
53      alert("You selected: " + selectedRows[i].OpportunityName);
54    }
55  }
56}

When the data table is rendered, each row displays a checkbox in the first column. The first row shows columns with the following data: Cloudhub, 20%, $25,000.00, jrogers@cloudhub.com, and (235) 223-5235. The last two columns are displayed as hyperlinks to represent an email address and telephone number.

Selecting any number of rows via checkboxes or a radio button in the selection column emits the onrowselection event. The event.detail.selectedRows property contains a list of all selected rows after any checkbox or radio button interaction. Alternatively, the event.detail.config.value contains a single id value of the row that was toggled.

This JavaScript function displays the email addresses of all rows as they're selected.

1getSelectedEmail(event) {
2    // Display the Contact of the selected rows
3    event.detail.selectedRows.forEach((selectedRow) => {
4        alert('Selected email addresses: ' + selectedRow.Contact);
5    });
6}

Use the event.detail.config.action property to keep a running list of rows that have been selected or deselected. event.detail.config.action has four possible values:

• selectAllRows: all rows are selected via the checkbox in the column header
• deselectAllRows: all rows are deselected via the checkbox in the column header
• rowSelect: single row is selected via the row checkbox
• rowDeselect: single row is deselected via the row checkbox

This JavaScript example keeps two running lists of row objects: a list of rows that have ever been selected and a list of row objects that are currently selected.

1selectedData = [];
2currentlySelectedData = [];
3
4handleRowSelection(event) {
5    switch (event.detail.config.action) {
6        case 'selectAllRows':
7            for (let i = 0; i < event.detail.selectedRows.length; i++) {
8                selectedData.push(event.detail.selectedRows[i]);
9                currentlySelectedData.push(event.detail.selectedRows[i]);
10            }
11            break;
12        case 'deselectAllRows':
13            currentlySelectedData = [];
14            break;
15        case 'rowSelect':
16            selectedData.push(event.detail.config.value);
17            break;
18        case 'rowDeselect':
19            index = currentlySelectedData.indexOf(event.detail.config.value);
20            if (index !== -1) {
21                array.splice(index, 1);
22            }
23            break;
24        default:
25            break;
26    }
27}

To return the data in each selected row, use the getSelectedRows() method. This example displays the data of the selected row(s) in a paragraph.

1<lightning-datatable
2    lwc:ref="dt"
3    key-field="id"
4    data={data}
5    columns={columns}></lightning-datatable>
6<lightning-button
7    label="Get Selected Row"
8    onclick={handleGetSelected}></lightning-button>
9<p>{selectedStr}</p>

To query your datatable, use the lwc:ref directive. This example uses lwc:ref="dt" where dt is the unique reference. Call the reference using this.refs.dt.

1import { LightningElement } from "lwc";
2
3// Define columns (COLS) here
4// Define or retrieve data (DATA) here
5
6export default class DatatableExample extends LightningElement {
7  data = DATA;
8  columns = COLS;
9  selected;
10
11  handleGetSelected() {
12    this.selected = this.refs.dt.getSelectedRows();
13  }
14
15  get selectedStr() {
16    return this.selected ? JSON.stringify(this.selected) : "";
17  }
18}

For example, if two rows are selected and you click the Get Selected Row button, the paragraph displays:

1[
2  {
3    "name": "Name (0)",
4    "website": "www.salesforce.com",
5    "amount": 80,
6    "phone": "7352970211",
7    "closeAt": "2025-01-16T06:37:06.606Z"
8  },
9  {
10    "name": "Name (1)",
11    "website": "www.salesforce.com",
12    "amount": 81,
13    "phone": "3746646998",
14    "closeAt": "2025-02-01T06:37:06.606Z"
15  }
16]

To return a simple list of records, use the getListUi wire adapter. To select certain accounts using SOQL, use an Apex method. See Call Apex Methods.

This example loads the first 10 contacts in the datatable using a SOQL query.

1public with sharing class ContactController {
2
3    @AuraEnabled(cacheable=true)
4    public static List<Contact> getContactList() {
5        return [SELECT Id, FirstName, LastName, Title, Phone, Email FROM Contact LIMIT 10];
6    }
7}

The template wires up the datatable to the contact records using the id field.

1<template>
2<lightning-datatable
3    key-field="Id"
4    data={contacts.data}
5    columns={columns}>
6</template>

Load the columns using JavaScript. This example wires the getContactList Apex method to the contacts property.

1import { LightningElement, wire } from "lwc";
2import getContactList from "@salesforce/apex/ContactController.getContactList";
3
4const columns = [
5  { label: "First Name", fieldName: "FirstName" },
6  { label: "Last Name", fieldName: "LastName" },
7  { label: "Title", fieldName: "Title" },
8  { label: "Phone", fieldName: "Phone", type: "phone" },
9  { label: "Email", fieldName: "Email", type: "email" },
10];
11export default class ApexDatatableExample extends LightningElement {
12  error;
13  columns = columns;
14
15  @wire(getContactList)
16  contacts;
17}

Use the following column properties to customize the behavior and visual aspects of your columns.

The data table formats the data cells of a column based on the type you specify for the column. To get correct formatting, specify a type that matches the field type you pass in to a column.

The default data type for a column is text. Object values passed into a text type column are displayed as an empty string.

For number and string values like percent, currency, date, email, and phone numbers, the text type column displays the unformatted value of the string. For example, specify type: 'date' in the column definition if you're passing in a date to the column. The date is then formatted according to the user's Salesforce locale. If you don't specify the date type, the retrieved date string is formatted as text.

Additionally, specify type: 'boolean' if you're passing in a boolean value to a column to display a checkmark for a true value. Passing in a boolean value to a column of text type displays the value as true or false.

Each data type is associated with a base Lightning component. For example, the text type renders the associated data using a lightning-formatted-text component. The phone type renders the associated data using a lightning-formatted-phone component, and the phone number is formatted for the user's locale.

To customize your output, pass in the attributes of the base component via the typeAttributes property. Not all attributes on a base component are supported. For more information, see the table on supported type attributes below.

The properties you pass with typeAttributes must be specified using the format shown here, not the format that's used for Lightning web component attributes in your HTML template. For example, although lightning-formatted-number recognizes a currency-code attribute, you must specify it as currencyCode with the typeAttributes property. For supported attribute values, refer to the component's documentation.

Valid data types and their supported attributes include:

In some situations, multiple columns reference the same fieldName but have different fieldApiNames and different ways of working with the field information. To give a column a unique ID when using the same field name for two columns, use the attribute columnKey instead of fieldName on one of the column definitions.

1get columns() {
2    return [
3        // Column using 'fieldName' as identifier
4        {
5            label: 'Lead',
6            fieldName: 'leadId',
7            ...
8        },
9        // Column using 'columnKey' as identifier
10        {
11            label: 'Company',
12            columnKey: 'leadCompany',
13            fieldName: 'leadId',
14            ...
15        }
16    ]
17}

To customize the formatting based on the data type, pass in the attributes for the corresponding base Lightning component. For example, to display the URL value as a tooltip on a URL, pass in the tooltip value.

1const columns = [
2  {
3    label: "Company Website",
4    fieldName: "website",
5    type: "url",
6    typeAttributes: { tooltip: { fieldName: "website" } },
7  },
8  // other column data
9];

For more information on attributes and their supported values, see the corresponding base component documentation.

For more information on creating your own data types, see Create a Custom Data Type.

Currency type displays a value based on the org currency and your Salesforce locale by default.

To override the default currency code, pass in a custom currencyCode value.

1const columns = [
2  {
3    label: "Amount",
4    fieldName: "amount",
5    type: "currency",
6    typeAttributes: { currencyCode: "EUR" },
7  },
8  // other column data
9];

To specify the granularity on a currency or percentage for inline editing, pass in the step attribute. For example, specify step: 0.01 to allow numbers with two decimal places, or step: 0.001 permits three decimal places. Specify step: 1 to require whole numbers. The default is 0.01. You can preserve the number of fraction digits for display using minimumFractionDigits and maximumFractionDigits.

1const columns = [
2  {
3    label: "Probability",
4    fieldName: "probability",
5    type: "percent",
6    typeAttributes: {
7      step: "0.00001",
8      minimumFractionDigits: "2",
9      maximumFractionDigits: "3",
10    },
11    editable: true,
12  },
13  //other column data
14];

For example, if you pass in probability: 0.21234 in your column data, the display value is 21.234%. When you inline edit, the step value is used to determine if your input is valid. If you pass in probability: 0.78, the display value is 78.00% because minimumFractionDigits is set to 2.

The locale set in the Salesforce user preferences determines the default formatting for date and time types.

The data table supports the date object and dates provided as ISO8601 formatted strings. Timestamps are not supported. These date formats can be displayed differently in a column. The default format is September 26, 2020, which corresponds to type: "date" or type: "date-local" and an empty typeAttributes property.

While the date type can be used to display date and time, the date-local type displays only the date. Here's how you can display Salesforce date and time data types in lightning-datatable.

Here are several ways to display date and time in a column.

09/26/2018

1{
2        label: "Date",
3        fieldName: "DueDate",
4        type: "date-local",
5        typeAttributes:{
6            month: "2-digit",
7            day: "2-digit"
8        }
9    }

Wednesday, September 26, 2018

1{
2        label: "Closed Date",
3        fieldName: "ClosedDate",
4        type: "date",
5        typeAttributes:{
6            weekday: "long",
7            year: "numeric",
8            month: "long",
9            day: "2-digit"
10        }
11    }

September 26, 2018, 12:00 PM

1{
2        label: "Arrival Time",
3        fieldName: "ArrivalTime",
4        type: "date",
5        typeAttributes:{
6            year: "numeric",
7            month: "long",
8            day: "2-digit",
9            hour: "2-digit",
10            minute: "2-digit"
11        }
12    }

Wednesday, September 26, 2018, 12:00 PM

1{
2        label: "Event Time",
3        fieldName: "EventTime",
4        type: "date",
5        typeAttributes:{
6            weekday: "long",
7            year: "numeric",
8            month: "long",
9            day: "2-digit",
10            hour: "2-digit",
11            minute: "2-digit"
12        }
13    }

The locale set in your Salesforce preferences determines the formatting. For more information, see the lightning-formatted-date-time documentation.

To horizontally align content in a column, use the cellAttributes property to pass in the alignment attribute and its setting, which can be left, right, or center.

1const columns = [
2  {
3    label: "Amount",
4    fieldName: "amount",
5    type: "currency",
6    cellAttributes: { alignment: "left" },
7  },
8  // other column data
9];

By default, number types align to the right. Number types include the currency, number, percent types.

The action type aligns to the center and cannot be overridden by the alignment attribute. All other types align to the left.

To override the alignment of the action type, consider using custom types and provide your own markup. See Create a Custom Data Type.

To display an icon instead of a label in the column header, specify the properties iconName and hideLabel in the column definition. Specify iconName as a utility icon.

To display a custom image in the column header, use the imgSrc property to specify a link to an image. To use an image in your org, upload the image as a static resource in the Static Resources setup page and then import the image from the @salesforce/resourceUrl module.

When both iconName and imgSrc are provided, iconName is used as a fallback if there is an error when attempting to load the image provided by imgSrc.

1const columns = [
2  {
3    label: "Ordering",
4    fieldName: "id",
5    type: "orderingButtons",
6    fixedWidth: 90,
7    iconName: "utility:trending",
8    imgSrc: "https://www.lightningdesignsystem.com/assets/images/product2.jpg",
9    hideLabel: true,
10  },
11  // other column data
12];

To support assistive technologies, set the label property for the column even though the label is hidden. Use standard header text that you'd use without an icon. The label text is used to set values for the icon's title and alternativeText attributes. The text is displayed as hover text. If the column has header controls the label text is used in aria-label for the header.

To append an icon to your data output, use cellAttributes and pass in these attributes.

You can add an icon with or without a label. This example defines two columns with icons. The first column specifies the utility:event icon for all rows using the iconName cell attribute, and the icon displays to the left of the data without a label. The second column uses computed values for the iconName and iconLabel and displays the icon to the right of the data.

1const columns = [
2  // simple icon
3  {
4    label: "Close date",
5    fieldName: "closeDate",
6    type: "date",
7    sortable: true,
8    cellAttributes: {
9      iconName: "utility:event",
10      iconAlternativeText: "Close Date",
11    },
12  },
13  // icon appended with a label
14  {
15    label: "Probability",
16    fieldName: "probability",
17    type: "percent",
18    cellAttributes: {
19      iconName: { fieldName: "confidenceDeltaIcon" },
20      iconLabel: { fieldName: "confidenceDelta" },
21      iconPosition: "right",
22      iconAlternativeText: "Percentage Probability",
23    },
24  },
25  // other column data
26];

Pass Lightning Design System (SLDS) classes to the class cell attribute when using standard data types. The classes you add are applied to all rows in a column.

1const columns = [
2  {
3    label: "Account Name",
4    fieldName: "Name",
5    cellAttributes: {
6      class: "slds-text-color_success slds-text-title_caps",
7    },
8  }, // other column data
9];

Custom classes are currently not supported. To apply custom styling on your datatable cells, create a custom data type and then apply your custom CSS classes. See Custom Data Type Layout and Styles.

You can display a lock icon on read-only fields to specify they're not editable. To specify that a column's field as read-only, set the column attribute editable to false and the column attribute displayReadOnlyIcon to true in the associated column definition. This example displays a lock icon on each field in a column called "Website."

1const columns = [
2    {
3        label: 'Website',
4        fieldName: 'website',
5        type: 'url',
6        editable: false,
7        displayReadOnlyIcon: true,
8    }

Infinite scrolling enables you to load a subset of data and then display more when users scroll to the end of the table. To enable infinite scrolling, specify enable-infinite-loading and provide an event handler using onloadmore. By default, data loading is triggered when you scroll down to 20px from the bottom of the table, but the offset can be changed using the load-more-offset attribute. Place the table in a container with a defined height to establish the bottom of the table. This limit enables the datatable to calculate when to load more and prevents infinite looping.

This example places the datatable in a container with a height of 500px. The table loads 50 more rows from the database when you reach the end of the table until there are no more data to load.

1<template>
2    <div style="height: 500px">
3        <lightning-datatable
4            columns={columns}
5            data={data}
6            key-field="Id"
7            enable-infinite-loading
8            onloadmore={loadMoreData}
9        >
10        </lightning-datatable>
11    </div>
12    {loadMoreStatus}
13</template>

The onloadmore event handler retrieves more data when you scroll to the bottom of the table until there are no more data to load. To display a spinner while data is being loaded, set the isLoading property to true.

1import { LightningElement, api } from "lwc";
2
3export default class DatatableExample extends LightningElement {
4  data = [];
5  columns = columnsDefs;
6  loadMoreStatus;
7  @api totalNumberOfRows;
8
9  loadMoreData(event) {
10    //Display a spinner to signal that data is being loaded
11    event.target.isLoading = true;
12    //Display "Loading" when more data is being loaded
13    this.loadMoreStatus = "Loading";
14    fetchData(50).then((data) => {
15      if (data.length >= this.totalNumberOfRows) {
16        event.target.enableInfiniteLoading = false;
17        this.loadMoreStatus = "No more data to load";
18      } else {
19        const currentData = this.data;
20        //Appends new data to the end of the table
21        const newData = currentData.concat(data);
22        this.data = newData;
23        this.loadMoreStatus = "";
24      }
25      event.target.isLoading = false;
26    });
27  }
28}

While this example uses a fixed number to denote the total number of rows, you can also use the SOQL SELECT syntax with the COUNT() function to return the number of rows in the object in your Apex controller. Then, set the result on the totalNumberOfRows attribute during initialization.

1SELECT COUNT(Id) FROM Contact

Scrolling to the top of the datatable programmatically is useful if there are more rows than can fit the datatable's height. To quickly return to the first row, use the scrollToTop() method.

1<template>
2    <div style="height: 500px;">
3        <lightning-datatable
4                key-field="id"
5                data={data}
6                columns={columns}
7                lwc:ref="datatable">
8        </lightning-datatable>
9    </div>
10    <lightning-button label="Scroll to Top" onclick={handleScroll}></lightning-button>
11</template>

To call the scrollToTop() method, use the lwc:ref directive. This example uses lwc:ref="datatable" where datatable is the unique reference. Call the reference using this.refs.datatable.

1import { LightningElement } from "lwc";
2
3const columns = [
4  // column data here
5];
6
7export default class DatatableScrollExample extends LightningElement {
8  data = [];
9  columns = columns;
10
11  handleScroll() {
12    this.refs.datatable.scrollToTop();
13  }
14}

The scrollToTop() method applies to the datatable's scrollbar only. It doesn't apply to the browser's scrollbar or an outer container scrollbar.

When you nest the datatable in a div container that specifies a height, the datatable header stays fixed at the top when you scroll through the rows. When the datatable is not nested in a div container with a height, the datatable header isn't fixed and can scroll. In the latter case, scrollToTop() doesn't scroll back to the top.

Header actions refer to tasks you can perform on a column of data, such as displaying only rows that meet a criteria provided by the column. You can perform actions on a column and handle them using the onheaderaction event handler.

Header actions are available in the dropdown menu in the column header. The default header actions available on each column are as follows. For more information, see Text Wrapping and Clipping.

To hide the dropdown menu with the default header actions on a column, pass in the hideDefaultActions property.

1const columns = [
2  { label: "Opportunity name", fieldName: "opportunityName", type: "text" },
3  {
4    label: "Amount",
5    fieldName: "amount",
6    type: "currency",
7    typeAttributes: { currencyCode: "EUR" },
8    hideDefaultActions: true,
9  },
10  //other column data
11];

If hideDefaultActions is set to true on a column that has custom header actions, the "Clip text" and "Wrap text" actions are removed from the actions dropdown menu, and the content is clipped by default. To wrap text when the default actions are hidden, set wrapText: true in the column definition.

To create a custom header action, use the attributes as follows.

For example, suppose you want to create a filter that displays only rows where the Publishing State column matches either the Published or Unpublished state.

1<template>
2    <lightning-datatable
3        columns={mycolumns}
4        data={mydata}
5        key-field="Id"
6        onheaderaction={handleHeaderAction}
7    >
8    </lightning-datatable>
9</template>

Bind the header actions to the actions column attribute, which can be done during initialization.

1const columns = [
2  // other column data
3  {
4    label: "Publishing State",
5    fieldName: "published",
6    type: "text",
7    actions: [
8      { label: "All", checked: true, name: "all" },
9      { label: "Published", checked: false, name: "show_published" },
10      { label: "Unpublished", checked: false, name: "show_unpublished" },
11    ],
12  },
13];

1handleHeaderAction: (event) {
2    // Retrieves the name of the selected filter
3    const actionName = event.detail.action.name;
4    // Retrieves the current column definition
5    // based on the selected filter
6    const colDef = event.detail.columnDefinition;
7    const columns = this.columns;
8    const activeFilter = this.activeFilter;
9
10    if (actionName !== activeFilter) {
11        var idx = columns.indexOf(colDef);
12        // Update the column definition with the updated actions data
13        var actions = columns[idx].actions;
14        actions.forEach((action) => {
15            action.checked = action.name === actionName;
16        });
17        this.activeFilter = actionName;
18        this.updateBooks();
19        this.columns = columns;
20    }
21}

Finally, display the rows to match the selected filter, which is performed by this.updateBooks().

1updateBooks(cmp) {
2    const rows = this.rawData;
3    const activeFilter = this.activeFilter;
4    const filteredRows = rows;
5    if (activeFilter !== 'all') {
6        filteredRows = rows.filter(function (row) {
7            return (activeFilter === 'show_published' ||
8              (activeFilter === 'show_unpublished');
9        });
10    }
11    this.data = filteredRows;
12}

Row-level actions refer to tasks you can perform on a row of data, such as updating or deleting the row. Static actions apply to all rows on the table. You can perform actions on each row and handle them using the onrowaction event handler.

Supported attributes for the row actions are as follows.

1<template>
2    <lightning-datatable
3        columns={mycolumns}
4        data={mydata}
5        key-field="Id"
6        onrowaction={handleRowAction}
7    >
8    </lightning-datatable>
9</template>

You must provide a list of actions to the columns data, which can be done during initialization. This JavaScript initializes the actions column and handles the actions on each row, displaying the row details and deleting the row when the action is clicked.

1import { LightningElement } from 'lwc';
2
3const actions = [
4    { label: 'Show details', name: 'show_details' },
5    { label: 'Delete', name: 'delete' }
6];
7
8const columns = [
9    // Other column data here
10    { type: 'action', typeAttributes: { rowActions: actions, menuAlignment: 'left' } }
11];
12
13export default class DatatableExample extends LightningElement {
14    data = [];
15    columns = columns;
16
17    handleRowAction(event) {
18            const action = event.detail.action;
19            const row = event.detail.row;
20            switch (action.name) {
21                case 'show_details':
22                    alert('Showing Details: ' + JSON.stringify(row));
23                    break;
24                case 'delete':
25                    const rows = this.data;
26                    const rowIndex = rows.indexOf(row);
27                    rows.splice(rowIndex, 1);
28                    this.data = rows;
29                    break;
30     }
31}

Dynamic actions are created based on the content of each row. When you click the dropdown menu, an asynchronous call is made to determine which actions to display for the particular row. The logic that determines which action to display can be created on initialization. In this example, the action and its label is evaluated when the dropdown menu is activated. Assume that we have an active column that displays the status of a contact (Active or Inactive), which determines which action to display (Deactivate or Activate).

1import { LightningElement } from 'lwc';
2
3const actions = [
4    { label: 'Show details', name: 'show_details' },
5    { label: 'Delete', name: 'delete' }
6];
7
8const columns = [
9    // Your column data
10];
11
12export default class DatatableExample extends LightningElement {
13    data = [];
14    columns = columns;
15
16    constructor() {
17        super();
18        this.columns = [
19            // Other column data here
20            { type: 'action', typeAttributes: { rowActions: this.getRowActions } },
21        ]
22    }
23
24    getRowActions(row, doneCallback) {
25        const actions = [];
26            if (row['isActive']) {
27                actions.push({
28                    'label': 'Deactivate',
29                    'iconName': 'utility:block_visitor',
30                    'name': 'deactivate'
31                });
32            } else {
33                actions.push({
34                    'label': 'Activate',
35                    'iconName': 'utility:adduser',
36                    'name': 'activate'
37                });
38            }
39            // simulate a trip to the server
40            setTimeout(() => {
41                doneCallback(actions);
42            }), 200);
43    }
44}

The previous example illustrates how to create and handle dynamic actions on the client-side only. You can make server calls and persist your record data changes via an Apex controller.

The width and height of the datatable is determined by the container element. A scroller is appended to the table body if there are more rows to display. For example, you can restrict the height to 300px by applying CSS styling to the container element.

1<div style="height: 300px;">
2    <!-- lightning-datatable goes here -->
3</div>

By default, columns are resizable. Users can click and drag the width to a minimum of 50px and a maximum of 1000px. Users can also resize the column width using the keyboard. For more information, see the Accessibility section.

You can customize the column widths in many ways. To specify your own width and disable resizing for a specific column, pass in fixedWidth to the column property. To specify an initial width and enable resizing for a specific column, pass in initialWidth to the column property.

1const columns = [
2  {
3    label: "Amount",
4    fieldName: "amount",
5    type: "currency",
6    initialWidth: 80,
7  },
8  // other column data
9];

Columns have a default minimum width of 50px and maximum width of 1000px. To change the minimum and maximum width of columns, use the min-column-width and max-column-width attributes. For example, if you want a user to be able to resize a column to a minimum of 80px, set min-column-width="80".

1<lightning-datatable
2    key-field="Id"
3    data={data}
4    columns={columns}
5    min-column-width="80"
6>
7</lightning-datatable>

To prevent users from resizing columns, specify resize-column-disabled in your markup. The table can still adjust its column widths when you resize the browser window or the width of the parent container changes. The resize-column-disabled attribute allows the table to resize columns when column-widths-mode is set to auto. See the next section for more information.

Resizing a column fires the resize event. For more information, See the Custom Events section.

1<lightning-datatable
2    key-field="Id"
3    data={data}
4    columns={columns}
5    onresize={handleResize}
6>
7</lightning-datatable>

To return the column widths, use the event.detail property on the onresize event handler.

1handleResize(event) {
2    const sizes = event.detail.columnWidths;
3}

The column-widths-mode attribute accepts values of fixed (default) or auto. To provide granular control on your column widths, use this attribute with the fixedWidth and initialWidth column properties. See Implementing Fixed Width Mode and Implementing Auto Width Mode for more information.

Widths for the following columns are fixed and cannot be changed.

• Row Number column
• Selection (checkbox) column
• Action column

Render columns with equal widths using column-widths-mode="fixed", which is the default setting. Any content that's too long to be displayed is clipped and appears with a trailing ellipsis. The column width is calculated by taking total available width and dividing equally among the columns.

You can specify your own widths using fixedWidth or initialWidth. The widths of the remaining columns without a specified fixedWidth or initialWidth value are equal.

Setting new data on the columns doesn't trigger resizing for columns, unless the new column definition specifies a change in fixedWidth or initialWidth values. In fixed mode, the columns automatically resizes and maintain equal widths when:

• The browser window is resized
• The parent container width for the datatable is changed
• The row-number-offset value is changed
• More or less data is passed in

When you manually resize a column to a larger width, the other columns maintain their widths, displaying a scrollbar to enable scrolling to the end of the table columns. When you manually resize to a smaller width, the other columns also maintain their widths.

You can resize manually using a mouse or a keyboard. On a keyboard, press enter in the header cell, tab to reach the resizer (column divider), and press the left or right arrow keys. On a touchscreen device, tap on the desired column resizer area, move to the desired width, and then release.

To trigger resizing of columns according to the length or size of data in a column, set column-widths-mode="auto". In auto width mode, the columns automatically resize when:

• Data changes in at least one row and the number of rows stays the same
• The column definition changes, such as a change in a column property or the number of columns

Pass a new reference of columns with changes for resize to take effect. The columns don't resize if there's only a change in the number of records in the data.

Column widths are calculated based on the width of the content displayed in the column and the total width of the table. Specify your own widths for particular columns using the fixedWidth or initialWidth properties. The widths of the columns without these properties are calculated based on the width of the content in the column and the remaining table width. If the columns definition is passed but no data is set yet, the columns are rendered based on the width of the column labels.

A column's width is limited by the max-column-width value, or 1000px by default. If a column width is calculated to be wider than the max-column-width value, the content is truncated and displayed with an ellipsis. If the column also specifies wrapText: true, the column results in a narrower width than if the column has clipped text.

A column's width is also limited by the min-column-width value, or 50px by default. If a column width is calculated to be narrower than the min-column-width value, the width is set to minimum column width and may have extra white space.

When you manually resize a column, the other columns maintain their widths. This behavior also occurs when a column is manually resized in fixed mode.

The columns keep their width ratios while adjusting the column widths when:

• The browser window is resized
• The parent container width for the datatable is changed
• The rowNumberOffset value is changed

Auto width mode is supported for containers with block display, which corresponds to the display: block CSS property. lightning-datatable doesn't fully support containers with display:inline-block or flex properties.

You can specify how many rows can be selected. When the maximum number of rows have been selected, the datatable disables the checkboxes that aren't selected. You can select another checkbox only after you deselect one of the selected checkboxes.

1<lightning-datatable
2    key-field="Id"
3    data={data}
4    columns={columns}
5    max-row-selection="5"
6>
7</lightning-datatable>

To enable single row selection, set max-row-selection="1". For single row selection, the datatable displays a radio button by default. Selecting the radio button selects the entire row of data and triggers the onrowselection event handler.

To render a checkbox for single row selection, set single-row-selection-mode="checkbox".

1<lightning-datatable
2    key-field="Id"
3    data={data}
4    columns={columns}
5    max-row-selection="1"
6    single-row-selection-mode="checkbox"
7>
8</lightning-datatable>

The selected-rows attribute enables you to preselect rows.

1<lightning-datatable
2    columns={columns}
3    data={data}
4    key-field="Id"
5    selected-rows={selectedRows}
6>
7</lightning-datatable>
8<lightning-button label="Select" onclick={handleSelect}> </lightning-button>

To select a row programmatically, pass in the row key-field value.

1// Load data via init handler first
2    // then handle programmatic selection
3    handleSelect() {
4        const rows = ['a'];
5        this.selectedRows = rows;
6    }

If max-row-selection is set to a value less than the number of selected rows, only the specified number of rows is selected. For example, if you set max-row-selection to 2 and pass in ['a', 'b', 'c'] to selected-rows, only rows a and b are selected.

Use the disabled-rows attribute to prevent users from changing the selection status of specified rows. Pass row identifiers into disabled-rows to prevent the rows from being selected. Pass row identifiers into both disabled-rows and selected-rows to prevent the rows from being deselected.

1<template>
2  <lightning-datatable
3    key-field="id"
4    columns={columns}
5    data={data}
6    disabled-rows={disabledRows}
7  >
8  </lightning-datatable>
9</template>

To disable a row programmatically, pass in the row key-field value to the disabled-rows attribute. For example, disabledRows = ['a', 'b']; where a and b correspond to the id values of the rows to be disabled. Rows that are both disabled and selected count towards the max-row-selection. For example, if you set max-row-selection to 2, and pass in ['a', 'b'] to both disabled-rows and selected-rows, the user can't select additional rows.

To enable sorting of row data by a column label, set sortable to true for the column on which you want to enable sorting. Clicking a column header sorts rows by ascending order, and clicking it subsequently reverses the order. Handle the onsort event to update the table with the new column index and sort direction.

Here's an example of an onsort event handler.

1data = data;
2columns = columns;
3sortDirection = 'asc';
4sortedBy;
5// The method onsort event handler
6handleSort(event) {
7    const { fieldName: sortedByField, sortDirection } = event.detail;
8    const cloneData = [...this.data];
9
10    cloneData.sort(this.sortBy(sortedByField, sortDirection === 'asc' ? 1 : -1));
11    this.data = cloneData;
12    this.sortDirection = sortDirection;
13    this.sortedBy = sortedByField;
14}

The handler assigns fieldName to sortedByField, which stores the name of the field that is currently being sorted. It also retrieves sortDirection from the sort event. On first sort, sortDirection is asc.

To keep the original data intact, cloneData creates a shallow copy of the data array. The handler passes in the comparison function sortBy and pass it to the array sort() method. Then it updates the data property with the sorted data, sortDirection with the new sort direction, and sortedBy with the sorted column.

For more information, see the Sortable Column example in the Example tab.

When you make a column editable, a pencil icon appears when you hover over the cells in that column. Clicking the icon or pressing the Enter key triggers inline editing. Inline editing is not supported for date and location fields.

Make a column editable by setting editable to true when you are defining your columns.

1{label: 'Amount', fieldName: 'amount', type: 'currency', typeAttributes: { currencyCode: 'EUR'}, editable : 'true'},
2    {label: 'Contact Email', fieldName: 'contact', type: 'email', editable : 'true'}

You can handle the oncancel, oncellchange, and onsave actions when the cell value changes or is saved. When the onsave action is used, the Cancel and Save button appears after a value cell changes and you press the Enter or Tab key, or move away from the cell.

1<template>
2    <lightning-datatable
3        key-field="Id"
4        data={data}
5        columns={columns}
6        onsave={handleSave}
7    >
8    </lightning-datatable>
9</template>

Retrieve the new value using event.detail.draftValues.

1handleSave(event) {
2    this.saveDraftValues = event.detail.draftValues;
3}

You can also program an external element, such as a button, to open an inline edit panel on the currently active cell or next editable cell in the datatable. Invoke the openInlineEdit() method in the external element that should direct a user to the first editable cell in your datatable component.

This example opens a datatable cell for inline edit when the user clicks an "Edit" button.

1import { LightningElement } from "lwc";
2export default class DatatableWithInlineEdit extends LightningElement {
3  data = [];
4  columns = columns;
5  rowOffset = 0;
6
7  handleClick() {
8    const dt = this.template.querySelector("lightning-datatable");
9    dt.openInlineEdit();
10  }
11}

For more information, see Display Data in a Table with Inline Editing.

When invalid data is entered, lightning-datatable can display client-side validation error messages at the row level and the table level.

To display errors for a column, you must make the column editable. When there's an editable column, lightning-datatable sets the show-row-number-column attribute to true to display the row errors in the number column. You can't override this setting.

For cells with standard types, the datatable uses the lightning-input component to handle editing of the cell content, and also to aid in handling error messages. To display error messages with custom data types, you can use lightning-input with the attribute data-inputable in your edit template. Then use the same techniques described here for displaying errors.

To display error messages for any editable columns, specify the errors attribute in your lightning-datatable component.

The errors attribute represents an object that specifies a rows property to provide information for the rows that contain errors and a table property to provide error information to display for the table.

The errors attribute represents an object that accepts one or both of these properties.

• rows-Provides information to display errors at the row level.
• table-Provides information to display errors at the bottom of the table. See Display Errors for the Table.

The rows object keys are the datatable’s key-field values, which provide a unique identifier for each row. Using this key-field value, you can provide custom errors on specific rows.

Customize the error messages using these properties in the rows object.

• title-Title for the error tooltip.
• messages-Text of error messages, listed in an array.
• fieldNames-Fields that triggered errors. Order the field names in a simple array to match the messages in the messages array.

To display custom messages under the fields with errors, you can specify fieldNames as an object instead of a simple array. See Display Custom Error Messages for Cells.

When an error is triggered, the datatable highlights in red the cell that corresponds to the specified fieldName value, and displays an error icon in the row number column. When you click the icon, a tooltip displays the text that's specified in title and messages.

For all types of error display, you must add the errors attribute to your component. This attribute's values can be modified in events that handle error conditions.

Your lightning-datatable component looks something like this.

1<template>
2    <lightning-datatable
3        key-field="Id"
4        data={data}
5        columns={columns}
6        errors={errors}
7    >
8    </lightning-datatable>
9    <lightning-button label="Trigger error" onclick={triggerError}>
10    </lightning-button>
11</template>

In this example, you can click a button to trigger the errors to display.

For row-level errors, define the error messages and field names in the errors object. To map the messages to fieldNames, specify an array of field names in the same order in which you specify the messages. In the example, when the error is triggered, the borders for the amount and contact cells in the row with the key-field 1 turn red to represent the error state. The messages are displayed in the tooltip in the number column, not on the cells themselves.

1triggerError(event) {
2           this.errors = {
3                rows: {
4                    1: {
5                        title: 'We found 2 errors.',
6                        messages: [
7                            'Enter a valid amount.',
8                            'Verify the email address and try again.'
9                        ],
10                        fieldNames: ['amount', 'contact']
11                    }
12                },
13            };
14        }

To display custom error messages under each field that has an error, you can specify the fieldNames property as an object of key-value pairs specifying the field name and the message like this:

1triggerError(event) {
2           this.errors = {
3                rows: {
4                    1: {
5                        title: 'We found 2 errors.',
6                        messages: [
7                            'Enter a valid amount.',
8                            'Verify the email address and try again.'
9                        ],
10                        fieldNames: {
11                            'amount': "Enter an amount greater than 100"
12                            'contact': "Specify a valid domain name"
13                        }
14
15                    }
16                },
17            };
18        }

If a cell is in the error state, the error message appears below the field when you click the edit icon to correct the entry. If you want to display the error icon and tooltip in the number column in addition to the field level message, also include the title and messages properties.

To display error messages at the bottom of the table, use the table property in the error object like this:

1triggerError(event) {
2           this.errors = {
3                table: {
4                    title: 'Your entry cannot be saved. Fix the errors and try again.',
5                    messages: [
6                        'Row 1 amount must be number',
7                        'Row 1 email is invalid'
8                    ]
9                }
10            };
11        }

When you use the table property, if an error occurs in an edited cell, the datatable displays an error icon in the bottom bar next to the Cancel and Save buttons. Click the icon to display a tooltip with the values of the title and messages properties that are set for the table property. The table-level errors require the table bottom bar to be present. Don’t include the attribute suppress-bottom-bar in the lightning-datatable component.

To display errors on rows and at the bottom of the table, declare both the rows and table properties in the errors object.

1triggerError(event) {
2           this.errors = {
3                rows: {
4                    1: {
5                        title: 'We found 2 errors.',
6                        messages: [
7                            'Enter a valid amount.',
8                            'Verify the email address and try again.'
9                        ],
10                        fieldNames: {
11                            'amount': "Enter an amount greater than 100"
12                            'contact': "Specify a valid domain name"
13                        }
14                    }
15                },
16               table: {
17                    title: 'Your entry cannot be saved. Fix the errors and try again.',
18                    messages: [
19                        'Row 1 amount must be number',
20                        'Row 1 email is invalid'
21                    ]
22                }
23                    }
24                },
25            };
26        }

You can wrap or clip text within columns. Text wrapping expands the rows vertically to reveal more content. Text clipping truncates the content to a single line within the column.

To toggle between the two views, select Wrap text or Clip text from the dropdown menu on the column header.

If the number of characters is more than what the column width can hold, content is clipped by default.

Text wrapping and clipping are not supported for row number columns and the following data types:

• action
• boolean
• button
• button-icon
• date-local

For text data type, text clipping converts newline characters to spaces and condenses multiple spaces or tabs to one space. Text clipping suppresses line breaks, truncates content to fit a single line in the column, and adds a trailing ellipsis. Text wrapping breaks lines and hyphenates words as needed to fit the column.

To enable text wrapping by default, set wrapText to true on the columns property.

1const columns = [
2  {
3    label: "Description",
4    fieldName: "description",
5    type: "text",
6    wrapText: true,
7  },
8  //other column data
9];

To display a number of lines of text in the column and hide the remaining lines, use wrap-text-max-lines. This example displays three lines of text and hides the rest; the text on line 3 is truncated and displayed with an ellipsis.

1<lightning-datatable
2    data={data}
3    columns={columns}
4    key-field="Id"
5    wrap-text-max-lines="3"
6>
7</lightning-datatable>

Handle the selection of Wrap text or Clip text on the column header using the onheaderaction handler. To return the name of the action, use the event.target.action.name property.

You can also wrap or clip the text in the column header with the wrap-table-header attribute. The property has three possible values:

• none (default)
• all
• by-column

none causes clipping on all column headers and all causes wrapping on all column headers. by-column wraps the header for columns that have the Wrap text setting enabled and clips the header for columns that have the Clip text setting enabled.

lightning-datatable renders with a grid role and a polite live region that announces whether the table is in navigation mode or action mode. To toggle action mode, tab into the table and then press the Enter key or Space Bar. To toggle back to navigation mode, press the Esc key to return focus to the cell. For more information about the different modes, see Toggle Between Navigation and Action Modes.

Each row header renders with an aria-label attribute with the labels you provide for the column definition. By default, the row number column renders with aria-label="Row Number" and cannot be changed. When row selection is enabled, each row renders with aria-selected set to true or false depending on whether the row is selected. Each cell renders with a gridcell role.

Use the following aria attributes on lightning-datatable to provide a caption or description on your table for assistive technologies. These attributes are rendered on the <table> element.

When using aria-label, consider using aria-describedby to provide supplemental information. We don't recommend using aria-label together with aria-labelledby. When there's visible text that labels an element, consider using aria-labelledby instead of aria-label.

If you use aria-describedby, the element that provides the description doesn't need to be visible. For more information, see MDN web docs: aria-describedby.

Use the aria-label attribute to provide a more descriptive label for the datatable for assistive technology. The aria-label attribute and its value are passed down to the rendered table element. On pages with multiple tables, aria-label helps users identify which table they're accessing.

Set the attribute in lightning-datatable in your template.

1<lightning-datatable aria-label="Account Details by Year for EMEA Region">
2</lightning-datatable>

Change the ARIA label dynamically using the ariaLabel property.

1const myLightningDataTableElement = this.template.querySelector("lightning-datatable");
2myLightningDataTableElement.ariaLabel = "Account Details by Revenue for EMEA Region";

The aria-label attribute doesn't support empty strings. If you set aria-label="" in the HTML or .ariaLabel = "" in JavaScript, the table's aria-label attribute is hidden, not rendered with an empty string. An empty label string can confuse screen readers.

If you have descriptions on an element or on multiple elements for the table, set the aria-labelledby value with the ID or list of IDs of the elements.

1<h2 id="table-desc1">Account Details by Year</h2>
2<h3 id="table-desc2">EMEA Region</h3>
3<lightning-datatable
4    aria-labelledby="table-desc1 table-desc2"
5    key-field="Id"
6    data={data}
7    columns={columns}
8>
9</lightning-datatable>

lightning-datatable generates a unique string for the element and aria-labelledby value to prevent any naming conflicts with other <table> elements on the page. Always verify that your rendered table correctly matches the IDs of the descriptive text in the DOM with a screen reader like JAWS or VoiceOver.

You can use data tables in navigation mode and action mode using the keyboard. To enter navigation mode, tab into the data table, which triggers focus on the first data cell in the table body on initial load. Use the arrow keys to move around the table. If you use the arrow key to move to another cell and then click away from the datatable, tab back into the datatable to place focus on the last cell you were on.

To enter action mode, press Enter or the Spacebar. You can navigate to each actionable element in the table using the Tab key.

When focus is on a cell that contains a link, press Enter to activate the link. If the link is a URL, the browser directs you to the website. If the link is a phone number or email, your browser prompts you to open the appropriate app for the link.

When using custom types, add additional attributes to make all elements of the component accessible. To make elements focusable, pass tabindex={internalTabIndex} all the way down to every component or element in the custom type. All focusable elements also must include data-navigation="enable". If you don't want the element to be focusable, use tabindex=-1. For more information, see Datatable Accessibility in the Lightning Web Components Developer Guide.

Columns can be resized in action mode. The component announces the column width during a resize. First, navigate to the column header using the arrow keys. Then, press the Tab key to activate the column divider to resize a column. You can resize a column by increasing or decreasing its width using one of the following key combinations.

• Right and Left Arrow keys
• Up and Down Arrow keys
• Page Up and Page Down keys

When you resize a column, the new column width is announced by assistive technology. To finish resizing the column and return to navigation mode, press the Esc key.