--- schema_version: "1" id: f076e05bb05453a59488cb34040505d0273ae60ae9413099c50a6c3ad4ea599f title: Datatable collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/datatable/lightning-datatable.md canonical_url: https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-datatable.html source_site: developer.salesforce.com content_type: documentation content_hash: a17970f4c90bd21b0f3073d6e30284ed8c4e5af150b5a9a26d39f1159eed3c38 products: - Lightning Component Reference --- # Datatable **`lightning-datatable`** A table that displays rows and columns of data. **For Use In** Lightning Experience, Experience Builder Sites, Lightning Out (Beta), Standalone Lightning App ::::::tabset{tabs='["Example", "Develop", "Specifications"]'} :::::tab ::component-playground{component="datatable" model="lwc" namespace="lightning"} ::::: :::::tab `lightning-datatable` presents tabular data where each column renders the content based on the data type. For example, an email address is shown as a hyperlink with the `mailto:` URL scheme by specifying the `email` type. The default data type on a column is `text`. `lightning-datatable` isn't supported on mobile devices. Supported features include: - 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 Initialize the table by 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 that you provide in the `data` array uses `Id` and not `id`. ## Design `lightning-datatable` implements the data tables blueprint in the Salesforce Lightning Design System (SLDS). The data tables adapt to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use. | | SLDS 1 | SLDS 2 | | :------------- | :--------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- | | **Design** | [Data Tables](https://v1.lightningdesignsystem.com/components/data-tables/) | [Data Tables](https://www.lightningdesignsystem.com/components/data-tables/) | | **For Use In** | Lightning Experience, Experience Builder sites, Lightning Out (Beta), Standalone Lightning app | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) | ## Create a Data Table This example creates a table whose first column shows a checkbox for row selection. This column is visible 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. ```html ``` Here's the JavaScript that creates selectable rows and the `columns` object to their corresponding column data. The Probability column shows 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 shows percentages and an icon that denotes the increasing or decreasing confidence trend. The icon is specified with the `cellAttributes` property. See [Column Properties](#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`. ```javascript import { LightningElement } from "lwc"; const columns = [ { label: "Opportunity name", fieldName: "OpportunityName", type: "text" }, { label: "Probability", fieldName: "Probability", type: "percent", cellAttributes: { iconName: { fieldName: "TrendIcon" }, iconPosition: "right", }, }, { label: "Amount", fieldName: "Amount", type: "currency", typeAttributes: { currencyCode: "EUR", step: "0.001" }, }, { label: "Contact Email", fieldName: "Contact", type: "email" }, { label: "Contact Phone", fieldName: "Phone", type: "phone" }, ]; const data = [ { Id: "a", OpportunityName: "Cloudhub", Probability: 0.2, Amount: 25000, Contact: "jrogers@cloudhub.com", Phone: "2352235235", TrendIcon: "utility:down", }, { Id: "b", OpportunityName: "Quip", Probability: 0.78, Amount: 740000, Contact: "quipy@quip.com", Phone: "2352235235", TrendIcon: "utility:up", }, ]; export default class DatatableExample extends LightningElement { data = data; columns = columns; getSelectedName(event) { const selectedRows = event.detail.selectedRows; // Get that fieldName of the selected rows for (let i = 0; i < selectedRows.length; i++) { alert("You selected: " + selectedRows[i].OpportunityName); } } } ``` When the data table is rendered, each row has a checkbox in the first column. The first row shows columns with the data: Cloudhub, 20%, \$25,000.00, jrogers@cloudhub.com, and (235) 223-5235. The last two columns use hyperlinks to represent an email address and telephone number. ## Select Rows 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 returns the email addresses of all rows as they're selected. ```js getSelectedEmail(event) { // Get the Contact of the selected rows event.detail.selectedRows.forEach((selectedRow) => { alert('Selected email addresses: ' + selectedRow.Contact); }); } ``` 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. ```js selectedData = []; currentlySelectedData = []; handleRowSelection(event) { switch (event.detail.config.action) { case 'selectAllRows': for (let i = 0; i < event.detail.selectedRows.length; i++) { selectedData.push(event.detail.selectedRows[i]); currentlySelectedData.push(event.detail.selectedRows[i]); } break; case 'deselectAllRows': currentlySelectedData = []; break; case 'rowSelect': selectedData.push(event.detail.config.value); break; case 'rowDeselect': index = currentlySelectedData.indexOf(event.detail.config.value); if (index !== -1) { array.splice(index, 1); } break; default: break; } } ``` To return the data in each selected row, use the `getSelectedRows()` method. This example returns the data of the selected row(s) in a paragraph. ```html

{selectedStr}

``` 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`. ```javascript import { LightningElement } from "lwc"; // Define columns (COLS) here // Define or retrieve data (DATA) here export default class DatatableExample extends LightningElement { data = DATA; columns = COLS; selected; handleGetSelected() { this.selected = this.refs.dt.getSelectedRows(); } get selectedStr() { return this.selected ? JSON.stringify(this.selected) : ""; } } ``` For example, if two rows are selected and you click the **Get Selected Row** button, the paragraph shows: ```json [ { "name": "Name (0)", "website": "www.salesforce.com", "amount": 80, "phone": "7352970211", "closeAt": "2025-01-16T06:37:06.606Z" }, { "name": "Name (1)", "website": "www.salesforce.com", "amount": 81, "phone": "3746646998", "closeAt": "2025-02-01T06:37:06.606Z" } ] ``` ## Work with Data 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](https://developer.salesforce.com/docs/platform/lwc/guide/apex). This example loads the first 10 contacts in the datatable using a SOQL query. ```java public with sharing class ContactController { @AuraEnabled(cacheable=true) public static List getContactList() { return [SELECT Id, FirstName, LastName, Title, Phone, Email FROM Contact LIMIT 10]; } } ``` The template wires up the datatable to the contact records using the `id` field. ```html ``` Load the columns using JavaScript. This example wires the `getContactList` Apex method to the `contacts` property. ```javascript import { LightningElement, wire } from "lwc"; import getContactList from "@salesforce/apex/ContactController.getContactList"; const columns = [ { label: "First Name", fieldName: "FirstName" }, { label: "Last Name", fieldName: "LastName" }, { label: "Title", fieldName: "Title" }, { label: "Phone", fieldName: "Phone", type: "phone" }, { label: "Email", fieldName: "Email", type: "email" }, ]; export default class ApexDatatableExample extends LightningElement { error; columns = columns; @wire(getContactList) contacts; } ``` ## Column Properties Use the following column properties to customize the behavior and visual aspects of your columns. | Property | Type | Description | | ------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | actions | object | Appends a dropdown menu of actions to a column. You must pass in a list of label-name pairs. | | cellAttributes | object | Provides additional customization using `alignment` and `class` properties, in addition to `icon*` properties such as for appending an icon to the output. For more information, see [Append an Icon to Column Data](#append-an-icon-to-column-data). | | editable | boolean | Specifies whether a column supports inline editing. The default is false. | | fieldName | string | Required. The name that binds the columns attributes to the associated data. Each columns attribute must correspond to an item in the data array. | | fixedWidth | integer | Specifies the width of a column in pixels and makes the column non-resizable. If both `fixedWidth` and `initialWidth` values are provided, `initialWidth` is ignored. | | hideDefaultActions | boolean | Specifies whether to hide the default header actions on a column. The default is false. For more information, see [Create Header Actions](#create-header-actions). | | hideLabel | boolean | Specifies whether to hide the label on a column. The default is false. For more information, see [Show an Icon Instead of a Column Label](#show-an-icon-instead-of-a-column-label). | | iconName | string | The Lightning Design System name of the icon. Names are written in the format standard:opportunity. The icon is appended to the left of the header label. If `hideLabel` is provided, only the icon is visible in the column header. | | imgSrc | string | The URI for a custom icon. The icon is appended to the left of the header label. If `hideLabel` is provided, only the icon is visible in the column header. If there's an error loading the URI, `iconName` is used as a fallback. | | initialWidth | integer | The width of the column when it's initialized, which must be within the `min-column-width` and`max-column-width` values, or within 50px and 1000px if they are not provided. | | label | string | Required. The text label in the column header. If `hideLabel` and `iconName` are set, the label is used as hover text for the icon and as the value of `aria-label`. | | sortable | boolean | Specifies whether the column can be sorted. The default is false. | | type | string | Required. The data type to be used for data formatting. For more information, see [Data Types](#data-types). | | typeAttributes | object | Provides custom formatting with component attributes for the data type. For example, currency-code for the currency type. For more information, see [Data Types](#data-types). | | wrapText | boolean | Specifies whether text in a column is wrapped when the table renders. Wrapped text vertically expands a row to reveal its full content. Use with `wrap-text-max-lines` to limit a number of lines before hiding the rest. For more information, see [Text Wrapping and Clipping](#text-wrapping-and-clipping). | ## Data Types 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 shown as an empty string. For number and string values like percent, currency, date, email, and phone numbers, the text type column shows 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 show a checkmark for a `true` value. Passing in a boolean value to a column of `text` type shows 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 by 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: | Type | Description | Supported Type Attributes | | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | action | Shows a dropdown menu using [lightning-button-menu](/docs/platform/lightning-component-reference/guide/lightning-button-menu.html) with actions as menu items. The default dropdown menu alignment, denoted by `menuAlignment`, is `right`. Valid options for `menuAlignment` are `right`, `left`, `auto`, `center`, `bottom-left`, `bottom-center`, and `bottom-right`. Use `alternativeText` to set the accessible name of the row action trigger button. The accessible name defaults to "Show actions" and can reference a row field name to provide a record-specific accessible name. See [Create Static Row-Level Actions](#create-static-row-level-actions). | rowActions (required), menuAlignment (defaults to right), alternativeText (defaults to "Show actions") | | boolean | Shows the icon utility:check if the value is true, and a blank value otherwise. | N/A | | button | Shows a button using [lightning-button](/docs/platform/lightning-component-reference/guide/lightning-button.html) | disabled, iconName, iconPosition, label, name, title, variant | | button-icon | Shows a button icon using [lightning-button-icon](/docs/platform/lightning-component-reference/guide/lightning-button-icon.html) | alternativeText, class, disabled, iconClass, iconName, name, title, variant | | currency | Shows a currency using [lightning-formatted-number](/docs/platform/lightning-component-reference/guide/lightning-formatted-number.html). See [ Currency and Percentages](#currency-and-percentages). | currencyCode, currencyDisplayAs, minimumIntegerDigits, minimumFractionDigits, maximumFractionDigits, minimumSignificantDigits, maximumSignificantDigits, step | | date | Shows a date and time based on the locale using [lightning-formatted-date-time](/docs/platform/lightning-component-reference/guide/lightning-formatted-date-time.html). See [Date and Time](#date-and-time). | day, era, hour, hour12, minute, month, second, timeZone, timeZoneName, weekday, year | | date-local | Shows a date that is formatted based on the locale using [lightning-formatted-date-time](/docs/platform/lightning-component-reference/guide/lightning-formatted-date-time.html). To include a time value, use the `date` type instead. The value passed is assumed to be in the browser local time zone and there is no time zone transformation. See [Date and Time](#date-and-time). | day, month, year | | email | Shows an email address using [lightning-formatted-email](/docs/platform/lightning-component-reference/guide/lightning-formatted-email.html) | N/A | | location | Shows a latitude and longitude of a location using [lightning-formatted-location](/docs/platform/lightning-component-reference/guide/lightning-formatted-location.html) | latitude, longitude | | number | Shows a number using [lightning-formatted-number](/docs/platform/lightning-component-reference/guide/lightning-formatted-number.html) | minimumIntegerDigits, minimumFractionDigits, maximumFractionDigits, minimumSignificantDigits, maximumSignificantDigits | | percent | Shows a percentage using [lightning-formatted-number](/docs/platform/lightning-component-reference/guide/lightning-formatted-number.html). See [Currency and Percentages](#currency-and-percentages). | minimumIntegerDigits, minimumFractionDigits, maximumFractionDigits, minimumSignificantDigits, maximumSignificantDigits, step | | phone | Shows a phone number using [lightning-formatted-phone](/docs/platform/lightning-component-reference/guide/lightning-formatted-phone.html) | N/A | | text | Shows text using [lightning-formatted-text](/docs/platform/lightning-component-reference/guide/lightning-formatted-text.html). This is the default data type. | linkify | | url | Shows a URL using [lightning-formatted-url](/docs/platform/lightning-component-reference/guide/lightning-formatted-url.html) | label, target, tooltip | 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. ```javascript get columns() { return [ // Column using 'fieldName' as identifier { label: 'Lead', fieldName: 'leadId', ... }, // Column using 'columnKey' as identifier { label: 'Company', columnKey: 'leadCompany', fieldName: 'leadId', ... } ] } ``` ## Custom Formatting To customize the formatting based on the data type, pass in the attributes for the corresponding base Lightning component. For example, to show the URL value as a tooltip on a URL, pass in the `tooltip` value. ```javascript const columns = [ { label: "Company Website", fieldName: "website", type: "url", typeAttributes: { tooltip: { fieldName: "website" } }, }, // other column data ]; ``` 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](https://developer.salesforce.com/docs/platform/lwc/guide/data-table-custom-types). ### Currency and Percentages 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. ```javascript const columns = [ { label: "Amount", fieldName: "amount", type: "currency", typeAttributes: { currencyCode: "EUR" }, }, // other column data ]; ``` 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`. ```javascript const columns = [ { label: "Probability", fieldName: "probability", type: "percent", typeAttributes: { step: "0.00001", minimumFractionDigits: "2", maximumFractionDigits: "3", }, editable: true, }, //other column data ]; ``` 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`. ### Date and Time 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 show Salesforce date and time data types in `lightning-datatable`. Salesforce Data Type|Datatable Data Type|Description -----|-----|----- DateTime|date|Expects date and time as input, and formats it according to the user's locale. Date|date-local|Expects date as input, and formats it according to the user's locale. Does not include time conversion. Here are several ways to show date and time in a column. 09/26/2018 ```javascript { label: "Date", fieldName: "DueDate", type: "date-local", typeAttributes:{ month: "2-digit", day: "2-digit" } } ``` Wednesday, September 26, 2018 ```javascript { label: "Closed Date", fieldName: "ClosedDate", type: "date", typeAttributes:{ weekday: "long", year: "numeric", month: "long", day: "2-digit" } } ``` September 26, 2018, 12:00 PM ```javascript { label: "Arrival Time", fieldName: "ArrivalTime", type: "date", typeAttributes:{ year: "numeric", month: "long", day: "2-digit", hour: "2-digit", minute: "2-digit" } } ``` Wednesday, September 26, 2018, 12:00 PM ```javascript { label: "Event Time", fieldName: "EventTime", type: "date", typeAttributes:{ weekday: "long", year: "numeric", month: "long", day: "2-digit", hour: "2-digit", minute: "2-digit" } } ``` The locale set in your Salesforce preferences determines the formatting. For more information, see the [lightning-formatted-date-time](/docs/platform/lightning-component-reference/guide/lightning-formatted-date-time.html) documentation. ## Align Content in A Column 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`. ```javascript const columns = [ { label: "Amount", fieldName: "amount", type: "currency", cellAttributes: { alignment: "left" }, }, // other column data ]; ``` 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](https://developer.salesforce.com/docs/platform/lwc/guide/data-table-custom-types). ## Show an Icon Instead of a Column Label To show 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](https://v1.lightningdesignsystem.com/icons/#utility). 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](https://developer.salesforce.com/docs/platform/lwc/guide/create-resources.html). 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`. ```javascript const columns = [ { label: "Ordering", fieldName: "id", type: "orderingButtons", fixedWidth: 90, iconName: "utility:trending", imgSrc: "https://www.lightningdesignsystem.com/assets/images/product2.jpg", hideLabel: true, }, // other column data ]; ``` 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 shown as hover text. If the column has header controls the label text is used in `aria-label` for the header. ## Append an Icon to Column Data To append an icon to your data output, use `cellAttributes` and pass in these attributes. | Attribute | Description | | ------------------- | ----------------------------------------------------------------------------------------------------------------------- | | iconName | Required. The Lightning Design System name of the icon, for example, utility:down. | | iconLabel | The label for the icon to be displayed on the right of the icon. | | iconPosition | The position of the icon relative to the data. Valid options include `left` and `right`. This value defaults to `left`. | | iconAlternativeText | Descriptive text for the icon. | 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 appears to the left of the data without a label. The second column uses computed values for the `iconName` and `iconLabel` and shows the icon to the right of the data. ```javascript const columns = [ // simple icon { label: "Close date", fieldName: "closeDate", type: "date", sortable: true, cellAttributes: { iconName: "utility:event", iconAlternativeText: "Close Date", }, }, // icon appended with a label { label: "Probability", fieldName: "probability", type: "percent", cellAttributes: { iconName: { fieldName: "confidenceDeltaIcon" }, iconLabel: { fieldName: "confidenceDelta" }, iconPosition: "right", iconAlternativeText: "Percentage Probability", }, }, // other column data ]; ``` ## Add Styles To Columns 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. ```javascript const columns = [ { label: "Account Name", fieldName: "Name", cellAttributes: { class: "slds-text-color_success slds-text-title_caps", }, }, // other column data ]; ``` 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](https://developer.salesforce.com/docs/platform/lwc/guide/data-table-custom-types-styling). ## Show Indicators for Read-Only Fields You can show 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 shows a lock icon on each field in a column called "Website." ```javascript const columns = [ { label: 'Website', fieldName: 'website', type: 'url', editable: false, displayReadOnlyIcon: true, } ``` ## Infinite Scrolling Infinite scrolling enables you to load a subset of data and then shows 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. ```html ``` 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 show a spinner while data is being loaded, set the `isLoading` property to `true`. ```javascript import { LightningElement, api } from "lwc"; export default class DatatableExample extends LightningElement { data = []; columns = columnsDefs; loadMoreStatus; @api totalNumberOfRows; loadMoreData(event) { //Show a spinner to signal that data is being loaded event.target.isLoading = true; //Show "Loading" when more data is being loaded this.loadMoreStatus = "Loading"; fetchData(50).then((data) => { if (data.length >= this.totalNumberOfRows) { event.target.enableInfiniteLoading = false; this.loadMoreStatus = "No more data to load"; } else { const currentData = this.data; //Appends new data to the end of the table const newData = currentData.concat(data); this.data = newData; this.loadMoreStatus = ""; } event.target.isLoading = false; }); } } ``` 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. ``` SELECT COUNT(Id) FROM Contact ``` ## Scroll Back to the Top 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. ```html ``` To call the `scrollToTop()` method, use [the `lwc:ref` directive](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-dom-work.html#refs). This example uses `lwc:ref="datatable"` where `datatable` is the unique reference. Call the reference using `this.refs.datatable`. ```javascript import { LightningElement } from "lwc"; const columns = [ // column data here ]; export default class DatatableScrollExample extends LightningElement { data = []; columns = columns; handleScroll() { this.refs.datatable.scrollToTop(); } } ``` 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. ## Create Header Actions Header actions refer to tasks you can perform on a column of data, such as showing 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](#text-wrapping-and-clipping). | Action Name | Description | | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Wrap text | Expands the row vertically to reveal more content if content is wider than the column width. Use `wrap-text-max-lines` to determine the number of lines to show when content is wrapped. | | Clip text | Truncates content to a single line with an ellipsis if content is wider than the column width. Content is clipped by default. | To hide the dropdown menu with the default header actions on a column, pass in the `hideDefaultActions` property. ```javascript const columns = [ { label: "Opportunity name", fieldName: "opportunityName", type: "text" }, { label: "Amount", fieldName: "amount", type: "currency", typeAttributes: { currencyCode: "EUR" }, hideDefaultActions: true, }, //other column data ]; ``` 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. | Attribute | Description | | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | label | Required. The label for the action. | | name | Required. The name of the action, which identifies the selected action. | | checked | Specifies whether a check mark is shown to the left of the action label. If true, a check mark is shown to the left of the menu item. If false, a check mark is not shown but there is space to accommodate one. | | disabled | Specifies whether the action can be selected. If true, the action item is shown as disabled. This value defaults to false. | | iconName | The name of the icon that appears to the right of the action item. | For example, suppose you want to create a filter that shows only rows where the Publishing State column matches either the Published or Unpublished state. ```html ``` Bind the header actions to the `actions` column attribute, which can be done during initialization. ```javascript const columns = [ // other column data { label: "Publishing State", fieldName: "published", type: "text", actions: [ { label: "All", checked: true, name: "all" }, { label: "Published", checked: false, name: "show_published" }, { label: "Unpublished", checked: false, name: "show_unpublished" }, ], }, ]; ``` ```javascript handleHeaderAction: (event) { // Retrieves the name of the selected filter const actionName = event.detail.action.name; // Retrieves the current column definition // based on the selected filter const colDef = event.detail.columnDefinition; const columns = this.columns; const activeFilter = this.activeFilter; if (actionName !== activeFilter) { var idx = columns.indexOf(colDef); // Update the column definition with the updated actions data var actions = columns[idx].actions; actions.forEach((action) => { action.checked = action.name === actionName; }); this.activeFilter = actionName; this.updateBooks(); this.columns = columns; } } ``` Finally, return the rows to match the selected filter, which is performed by `this.updateBooks()`. ```javascript updateBooks(cmp) { const rows = this.rawData; const activeFilter = this.activeFilter; const filteredRows = rows; if (activeFilter !== 'all') { filteredRows = rows.filter(function (row) { return (activeFilter === 'show_published' || (activeFilter === 'show_unpublished'); }); } this.data = filteredRows; } ``` ## Create Static Row-Level Actions 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. | Attribute | Description | | --------- | -------------------------------------------------------------------------------------------------------------------------- | | label | Required. The label for the action. | | name | Required. The name of the action, which identifies the selected action. | | disabled | Specifies whether the action can be selected. If true, the action item is shown as disabled. This value defaults to false. | | iconName | The name of the icon that appears to the right of the action item. | ```html ``` 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, showing the row details and deleting the row when the action is clicked. ```javascript import { LightningElement } from 'lwc'; const actions = [ { label: 'Show details', name: 'show_details' }, { label: 'Delete', name: 'delete' } ]; const columns = [ // Other column data here { type: 'action', typeAttributes: { rowActions: actions, menuAlignment: 'left' } } ]; export default class DatatableExample extends LightningElement { data = []; columns = columns; handleRowAction(event) { const action = event.detail.action; const row = event.detail.row; switch (action.name) { case 'show_details': alert('Showing Details: ' + JSON.stringify(row)); break; case 'delete': const rows = this.data; const rowIndex = rows.indexOf(row); rows.splice(rowIndex, 1); this.data = rows; break; } } ``` By default, screen readers announce the row action trigger button as "Show actions" on every row. To give the button a more descriptive, record-specific accessible name, use `alternativeText`. Bind it to a row field name so each row gets a distinct accessible name. ```javascript const columns = [ // Other column data here { type: "action", typeAttributes: { rowActions: actions, // Announces, for example, "Show actions for Acme Corp" alternativeText: { fieldName: "showActionsLabel" }, }, }, ]; ``` ## Create Dynamic Row-Level Actions 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 return for the particular row. The logic that determines which action to return 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 shows the status of a contact (Active or Inactive), which determines which action to show (Deactivate or Activate). ```javascript import { LightningElement } from 'lwc'; const actions = [ { label: 'Show details', name: 'show_details' }, { label: 'Delete', name: 'delete' } ]; const columns = [ // Your column data ]; export default class DatatableExample extends LightningElement { data = []; columns = columns; constructor() { super(); this.columns = [ // Other column data here { type: 'action', typeAttributes: { rowActions: this.getRowActions } }, ] } getRowActions(row, doneCallback) { const actions = []; if (row['isActive']) { actions.push({ 'label': 'Deactivate', 'iconName': 'utility:block_visitor', 'name': 'deactivate' }); } else { actions.push({ 'label': 'Activate', 'iconName': 'utility:adduser', 'name': 'activate' }); } // simulate a trip to the server setTimeout(() => { doneCallback(actions); }), 200); } } ``` 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. ## Resize Tables and Columns 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 show. For example, you can restrict the height to 300px by applying CSS styling to the container element. ```html
``` By default, columns are resizable. Users can resize the column 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](#accessibility) section. ### Work with Column Widths 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. ```javascript const columns = [ { label: "Amount", fieldName: "amount", type: "currency", initialWidth: 80, }, // other column data ]; ``` 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"`. ```html ``` 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](#custom-events) section. ```html ``` To return the column widths, use the `event.detail` property on the `onresize` event handler. ```javascript handleResize(event) { const sizes = event.detail.columnWidths; } ``` ### Manage Column Width Resize 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 [Use Fixed Width Mode](#use-fixed-width-mode) and [Use Auto Width Mode](#use-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 ### Use Fixed Width Mode Render columns with equal widths using `column-widths-mode="fixed"`, which is the default setting. Any content that's too long to be shown 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, showing 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. ### Use Auto Width Mode 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 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 shown 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. ## Specify Maximum Number of Selected Rows 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. ```html ``` ## Enable Single Row Selection To enable single row selection, set `max-row-selection="1"`. For single row selection, the datatable use 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"`. ```html ``` ## Select Rows Programmatically The `selected-rows` attribute enables you to preselect rows. ```html ``` To select a row programmatically, pass in the row `key-field` value. ```javascript // Load data via init handler first // then handle programmatic selection handleSelect() { const rows = ['a']; this.selectedRows = rows; } ``` 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. ## Disable Rows Programmatically 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. ```html ``` 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. ## Sort Data By Column 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. ```javascript data = data; columns = columns; sortDirection = 'asc'; sortedBy; // The method onsort event handler handleSort(event) { const { fieldName: sortedByField, sortDirection } = event.detail; const cloneData = [...this.data]; cloneData.sort(this.sortBy(sortedByField, sortDirection === 'asc' ? 1 : -1)); this.data = cloneData; this.sortDirection = sortDirection; this.sortedBy = sortedByField; } ``` 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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort). 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. ## Inline Editing 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. ```javascript {label: 'Amount', fieldName: 'amount', type: 'currency', typeAttributes: { currencyCode: 'EUR'}, editable : 'true'}, {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. ```html ``` Retrieve the new value using `event.detail.draftValues`. ```javascript handleSave(event) { this.saveDraftValues = event.detail.draftValues; } ``` 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. ```javascript import { LightningElement } from "lwc"; export default class DatatableWithInlineEdit extends LightningElement { data = []; columns = columns; rowOffset = 0; handleClick() { const dt = this.template.querySelector("lightning-datatable"); dt.openInlineEdit(); } } ``` For more information, see [Display Data in a Table with Inline Editing](https://developer.salesforce.com/docs/platform/lwc/guide/data-table-inline-edit). ## Handle Errors When invalid data is entered, `lightning-datatable` can show client-side validation error messages at the row level and the table level. To show 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 show 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 show 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 showing errors. To show 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 show for the table. The `errors` attribute represents an object that accepts one or both of these properties. - `rows`-Provides information to show errors at the row level. - `table`-Provides information to show errors at the bottom of the table. See [Show Errors for the Table](#show-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. - `rowTitle`-Optional string for the error icon's assistive text, which is used in place of the row's scope cell value. **note:** Set `rowTitle` when the scope cell value isn't a string, such as when the custom cell type outputs an object. Screen readers then announce a meaningful row label instead of `[object Object]`. If you don't set `rowTitle` and the scope cell value isn't a usable string, the assistive text falls back to `Row Number {N}`, where `{N}` is the row's 1-based index, so screen readers always announce a meaningful identifier. To show custom messages under the fields with errors, you can specify `fieldNames` as an object instead of a simple array. See [Show Custom Error Messages for Cells](#show-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 shows an error icon in the row number column. When you click the icon, a tooltip shows 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. ```html ``` In this example, you can click a button to show the errors. ## Show Errors on a Row 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 shown in the tooltip in the number column, not on the cells themselves. ```javascript triggerError(event) { this.errors = { rows: { 1: { title: 'We found 2 errors.', messages: [ 'Enter a valid amount.', 'Verify the email address and try again.' ], fieldNames: ['amount', 'contact'] } }, }; } ``` ## Show Custom Error Messages for Cells To show 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: ```javascript triggerError(event) { this.errors = { rows: { 1: { title: 'We found 2 errors.', messages: [ 'Enter a valid amount.', 'Verify the email address and try again.' ], fieldNames: { 'amount': "Enter an amount greater than 100" 'contact': "Specify a valid domain name" } } }, }; } ``` 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 show the error icon and tooltip in the number column in addition to the field level message, also include the `title` and `messages` properties. ## Show Errors for the Table To show error messages at the bottom of the table, use the `table` property in the `error` object like this: ```javascript triggerError(event) { this.errors = { table: { title: 'Your entry cannot be saved. Fix the errors and try again.', messages: [ 'Row 1 amount must be number', 'Row 1 email is invalid' ] } }; } ``` When you use the `table` property, if an error occurs in an edited cell, the datatable shows an error icon in the bottom bar next to the Cancel and Save buttons. Click the icon to show 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 show errors on rows and at the bottom of the table, declare both the `rows` and `table` properties in the `errors` object. ```javascript triggerError(event) { this.errors = { rows: { 1: { title: 'We found 2 errors.', messages: [ 'Enter a valid amount.', 'Verify the email address and try again.' ], fieldNames: { 'amount': "Enter an amount greater than 100" 'contact': "Specify a valid domain name" } } }, table: { title: 'Your entry cannot be saved. Fix the errors and try again.', messages: [ 'Row 1 amount must be number', 'Row 1 email is invalid' ] } } }, }; } ``` ## Text Wrapping and Clipping 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. ```javascript const columns = [ { label: "Description", fieldName: "description", type: "text", wrapText: true, }, //other column data ]; ``` To show a number of lines of text in the column and hide the remaining lines, use `wrap-text-max-lines`. This example shows three lines of text and hides the rest; the text on line 3 is truncated and shown with an ellipsis. ```html ``` 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. ### Text Wrapping in Column Headers 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. ## Accessibility `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](#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 `` element. | Attribute | Type | Description | | ---------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | aria-label | string | Provides an assistive label to identify a table from other tables on a page. | | aria-describedby | ID reference list | Specifies the ID or space-separated list of IDs that describes the current element. | | aria-labelledby | ID reference list | Specifies the ID or space-separated list of IDs of the element or elements that contain visible descriptive text to caption or describe the table. | 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](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby). ### Provide an Accessible Label for the Table 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. ```html ``` Change the ARIA label dynamically using the `ariaLabel` property. ```javascript const myLightningDataTableElement = this.template.querySelector("lightning-datatable"); myLightningDataTableElement.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. ### Provide an Accessible Caption for the Table 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. ```html

Account Details by Year

EMEA Region

``` `lightning-datatable` generates a unique string for the element and `aria-labelledby` value to prevent any naming conflicts with other `
` 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. ### Toggle Between Navigation and Action Modes 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](https://developer.salesforce.com/docs/platform/lwc/guide/data-table-a11y.html) in the Lightning Web Components Developer Guide. ### Resize Columns Using Arrow Keys 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. ### Resize Columns Using Your Mouse There are several ways to resize a column using your mouse. - Click and drag: To resize a column, click the column header divider and drag your mouse to the width that you want. - Click to activate resize mode: To resize a column, click the column header divider, move your mouse to the width that you want, and click again to commit the resize. To exit resize mode without committing the resize, press the Esc key or tab to remove focus from the column edge. ### Apply Focus on an Active Cell To programmatically apply focus to the active cell, use the `focus()` method. For example, you can click a button to move focus back to the last active cell on the datatable. ```html ``` 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`. ```javascript import { LightningElement } from "lwc"; // Define columns (COLS) here // Define or retrieve data (DATA) here export default class DatatableExample extends LightningElement { data = DATA; columns = COLS; selected; handleFocus() { this.refs.dt.focus(); } } ``` ## Usage Considerations This component has usage differences from its Aura counterpart. See [Base Components: Aura Vs Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-map-aura-lwc-components) in the Lightning Web Components Developer Guide. ## Custom Events **`cancel`** The event fired when the cancel button is pressed during inline editing. The `cancel` event does not return any parameter. The event properties are as follows. | Property | Value | Description | | ---------- | ----- | ------------------------------------------------------------------------------ | | bubbles | false | This event does not bubble. | | cancelable | true | This event can be canceled. You can call `preventDefault()` on this event. | | composed | false | This event does not propagate outside the template in which it was dispatched. | **`headeraction`** The event fired when a header action is selected, such as text wrapping, text clipping, or a custom header action. The `headeraction` event returns the following parameters. | Parameter | Type | Description | | ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | action | object | The action definition described in [Create Header Actions](#create-header-actions). | | columnDefinition | object | The column definition specified in the `columns` property, for example, the key-value pairs for `label`, `fieldName`, `type`, `typeAttributes`, and `wrapText`. See [Column Properties](#column-properties). | The event properties are as follows. | Property | Value | Description | | ---------- | ----- | ---------------------------------------------------------------------------------------------------------- | | bubbles | false | This event does not bubble. | | cancelable | false | This event has no default behavior that can be canceled. You cannot call `preventDefault()` on this event. | | composed | false | This event does not propagate outside the template in which it was dispatched. | **`loadmore`** The event fired when you scroll to the bottom of the table to load more data, until there are no more data to load. The `loadmore` event returns the following parameters. | Parameter | Type | Description | | --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ | | enableInfiniteLoading | boolean | Specifies whether infite loading is available on the table. | | isLoading | boolean | Specifies that data is loading and shows a spinner on the table. | | loadMoreOffset | integer | The number of pixels between the bottom of the table and the current scroll position, used to trigger more data loading. | The event properties are as follows. | Property | Value | Description | | ---------- | ----- | ---------------------------------------------------------------------------------------------------------- | | bubbles | false | This event does not bubble. | | cancelable | false | This event has no default behavior that can be canceled. You cannot call `preventDefault()` on this event. | | composed | false | This event does not propagate outside the template in which it was dispatched. | **`resize`** The event fired when the a table column is resized, which depends on which width mode you're using. In the default `fixed` width mode, the `resize` event is fired when: - The table renders initially - You manually resize a column - The number of columns changes on a subsequent rerender In `auto` width mode, the event is fired only when you manually resize a column. See [Use Fixed Width Mode](#use-fixed-width-mode) and [Use Auto Width Mode](#use-auto-width-mode) for more information. The `resize` event is _not_ fired in the following cases. - You resize the browser or viewport, causing adjustments in the column widths - You change the column definition, but not the number of columns, causing adjustments in the column widths. The `resize` event returns the following parameters. | Parameter | Type | Description | | --------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | columnWidths | object | The width of all columns, in pixels. For example, a table with 5 columns of 205px width each at initial render returns `[205, 205, 205, 205, 205]`. | | isUserTriggered | boolean | Specifies whether the column resize is caused by a user action. | The event properties are as follows. | Property | Value | Description | | ---------- | ----- | ---------------------------------------------------------------------------------------------------------- | | bubbles | false | This event does not bubble. | | cancelable | false | This event has no default behavior that can be canceled. You cannot call `preventDefault()` on this event. | | composed | false | This event does not propagate outside the template in which it was dispatched. | **`rowselection`** The event fired when the row is selected. The `rowselection` event returns the following parameter. | Parameter | Type | Description | | ------------- | ------ | ---------------------------------------------------------------------------------------------------------------------- | | selectedRows | object | The data in the rows that are selected. | | config.action | string | The type of selection event. Valid options include 'selectAllRows', 'deselectAllRows', 'rowSelect', and 'rowDeselect'. | The event properties are as follows. | Property | Value | Description | | ---------- | ----- | ---------------------------------------------------------------------------------------------------------- | | bubbles | false | This event does not bubble. | | cancelable | false | This event has no default behavior that can be canceled. You cannot call `preventDefault()` on this event. | | composed | false | This event does not propagate outside the template in which it was dispatched. | **`save`** The event fired when data is saved during inline editing. The `save` event returns the following parameter. | Parameter | Type | Description | | ----------- | ------ | -------------------------------------------------------- | | draftValues | object | The current value that's provided during inline editing. | The event properties are as follows. | Property | Value | Description | | ---------- | ----- | ---------------------------------------------------------------------------------------------------------- | | bubbles | false | This event does not bubble. | | cancelable | false | This event has no default behavior that can be canceled. You cannot call `preventDefault()` on this event. | | composed | false | This event does not propagate outside the template in which it was dispatched. | **`sort`** The event fired when a column is sorted. The `sort` event returns the following parameters. | Parameter | Type | Description | | ----------------- | ------- | -------------------------------------------------------------- | | fieldName | string | The fieldName that controls the sorting. | | isMultiColumnSort | boolean | Reserved for internal use. Defaults to false. | | sortDirection | string | The sorting direction. Valid options include 'asc' and 'desc'. | The event properties are as follows. | Property | Value | Description | | ---------- | ----- | ---------------------------------------------------------------------------------------------------------- | | bubbles | false | This event does not bubble. | | cancelable | false | This event has no default behavior that can be canceled. You cannot call `preventDefault()` on this event. | | composed | false | This event does not propagate outside the template in which it was dispatched. | ## LWC Recipes The [LWC Recipes GitHub repository](https://github.com/trailheadapps/lwc-recipes) contains code examples for Lightning Web Components that you can test in an org. For a recipe that uses `lightning-datatable`, see the `c-datatable-*` components in the LWC Recipes repo. ::::: :::::tab ::component-specification{component="datatable" model="lwc" namespace="lightning"} ::::: ::::::