lightning-base-components 1.22.3-alpha → 1.26.2-rc.0-alpha

package/src/lightning/datatable/__docs__/datatable.md

@@ -12,6 +12,9 @@ examples:
     - name: withInlineEdit
       label: Data Table with Inline Edit
       description: A data table with inline edit enabled, simulating server requests.
+    - name: withErrors
+      label: Data Table with Errors
+      description: A data table with inline edit enabled and error message support.
     - name: sorting
       label: Data Table with Sortable Column
       description: A data table with a column that can be sorted in ascending or descending order.
@@ -49,7 +52,7 @@ 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.
-The checkbox column is displayed by default, and you can hide it by adding `hide-checkbox-column` in your markup.
+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.
 
 ```html
@@ -65,12 +68,12 @@ Selecting the checkbox selects the entire row of data and triggers the `onrowsel
 ```
 
 Here's the JavaScript that creates selectable rows and the
-`columns` object to their corresponding column data. The Confidence column
+`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
-Confidence column displays percentages and an icon that denotes the increasing
+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.
@@ -84,8 +87,8 @@ import { LightningElement } from 'lwc';
 const columns = [
     { label: 'Opportunity name', fieldName: 'OpportunityName', type: 'text' },
     {
-        label: 'Confidence',
-        fieldName: 'Confidence',
+        label: 'Probability',
+        fieldName: 'Probability',
         type: 'percent',
         cellAttributes: {
             iconName: { fieldName: 'TrendIcon' },
@@ -106,7 +109,7 @@ const data = [
     {
         Id: 'a',
         OpportunityName: 'Cloudhub',
-        Confidence: 0.2,
+        Probability: 0.2,
         Amount: 25000,
         Contact: 'jrogers@cloudhub.com',
         Phone: '2352235235',
@@ -115,7 +118,7 @@ const data = [
     {
         Id: 'b',
         OpportunityName: 'Quip',
-        Confidence: 0.78,
+        Probability: 0.78,
         Amount: 740000,
         Contact: 'quipy@quip.com',
         Phone: '2352235235',
@@ -144,7 +147,7 @@ displayed as hyperlinks to represent an email address and telephone number.
 
 #### Managing Selected Rows
 
-Selecting a row or all rows via the checkbox column emits the `onrowselection` event. The `event.detail.selectedRows` property contains a list of all selected rows after any checkbox toggle. Alternatively, the `event.detail.config.value` contains a single `id` value of the row that was toggled.
+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.
 
@@ -196,6 +199,49 @@ handleRowSelection(event) {
 }
 ```
 
+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.
+
+```html
+ <lightning-datatable
+    lwc:ref="dt"
+    key-field="id"
+    data={data}
+    columns={columns}></lightning-datatable>
+<lightning-button 
+    label="Get Selected Row" 
+    onclick={handleGetSelected}></lightning-button>
+<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`.
+
+```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 displays:
+
+```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"}]
+```
+
 #### Retrieving Data Using an Apex Controller
 
 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).
@@ -260,6 +306,7 @@ aspects of your columns.
 | hideDefaultActions | boolean | Specifies whether to hide the default header actions on a column. The default is false. For more information, see **Creating Header Actions**.                                                                                                                                        |
 | hideLabel          | boolean | Specifies whether to hide the label on a column. The default is false. For more information, see **Displaying 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 displays 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 displays 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 displayed 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.                                                                                                                                                                                                                     |
@@ -369,8 +416,8 @@ To specify the granularity on a currency or percentage for inline editing, pass
 ```javascript
 const columns = [
     {
-        label: 'Confidence',
-        fieldName: 'confidence',
+        label: 'Probability',
+        fieldName: 'probability',
         type: 'percent',
         typeAttributes: {
             step: '0.00001',
@@ -383,7 +430,7 @@ const columns = [
 ];
 ```
 
-For example, if you pass in `confidence: 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 `confidence: 0.78`, the display value is `78.00%` because `minimumFractionDigits` is set to `2`.
+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`.
 
 #### Displaying Date and Time Using Type Attributes
 
@@ -495,6 +542,10 @@ To override the alignment of the `action` type, consider using custom types and
 
 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](https://www.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 = [
     {
@@ -503,6 +554,7 @@ const columns = [
         type: 'orderingButtons',
         fixedWidth: 90,
         iconName: 'utility:trending',
+        imgSrc: 'https://www.lightningdesignsystem.com/assets/images/product2.jpg',
         hideLabel: true,
     },
     // other column data
@@ -542,14 +594,14 @@ const columns = [
     },
     // icon appended with a label
     {
-        label: 'Confidence',
-        fieldName: 'confidence',
+        label: 'Probability',
+        fieldName: 'probability',
         type: 'percent',
         cellAttributes: {
             iconName: { fieldName: 'confidenceDeltaIcon' },
             iconLabel: { fieldName: 'confidenceDelta' },
             iconPosition: 'right',
-            iconAlternativeText: 'Percentage Confidence',
+            iconAlternativeText: 'Percentage Probability',
         },
     },
     // other column data
@@ -664,6 +716,48 @@ the `totalNumberOfRows` attribute during initialization.
     SELECT COUNT(Id) FROM Contact
 ```
 
+#### Scrolling 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
+<template>
+    <div style="height: 500px;">
+        <lightning-datatable
+                key-field="id"
+                data={data}
+                columns={columns}
+                lwc:ref="datatable">
+        </lightning-datatable>
+    </div>
+    <lightning-button label="Scroll to Top" onclick={handleScroll}></lightning-button>
+</template>
+```
+
+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.
+
 #### Creating Header Actions
 
 Header actions refer to tasks you can perform on a column of data, such
@@ -1031,6 +1125,37 @@ The columns keep their width ratios while adjusting the column widths when:
 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.
 
+#### Specifying 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
+<lightning-datatable
+    key-field="Id"
+    data={data}
+    columns={columns}
+    max-row-selection="5"
+>
+</lightning-datatable>
+```
+
+#### Enabling Single Row Selection
+
+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"`.
+
+```html
+<lightning-datatable
+    key-field="Id"
+    data={data}
+    columns={columns}
+    max-row-selection="1"
+    single-row-selection-mode="checkbox"
+>
+</lightning-datatable>
+```
+
 #### Selecting Rows Programmatically
 
 The `selected-rows` attribute enables programmatic selection of rows, which is
@@ -1148,16 +1273,35 @@ For more information, see [Display Data in a Table with Inline Editing](https://
 
 #### Displaying Errors
 
-You can trigger an error on a cell or multiple cells, which then turns the
-cell border red and displays a tooltip on the number column. The error
-messages appear when you hover over the tooltip. You must make the column
-editable. By making a column editable, the `show-row-number-column` attribute is
-always true and the number column is displayed.
+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.
 
-Based on the first example on this page, add the `errors` attribute to your
-component.
+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.
 
-Your `lightning-datatable` component should look like this.
+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.
 
 ```html
 <template>
@@ -1173,18 +1317,18 @@ Your `lightning-datatable` component should look like this.
 </template>
 ```
 
-In this example, we are triggering the error with a `lightning-button`
-component.
+In this example, you can click a button to trigger the errors to display.
+
+#### Display 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 displayed in the tooltip in the number column, not on the cells themselves.
 
-Finally, define the errors and map them to `fieldNames`. When the error is
-triggered, the borders for the `amount` and `contact` cells turn red to
-represent the error state.
 
 ```javascript
     triggerError(event) {
            this.errors = {
                 rows: {
-                    b: {
+                    1: {
                         title: 'We found 2 errors.',
                         messages: [
                             'Enter a valid amount.',
@@ -1193,17 +1337,90 @@ represent the error state.
                         fieldNames: ['amount', 'contact']
                     }
                 },
+            };
+        }
+```
+
+#### Display Custom Error Messages for Cells
+
+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:
+
+
+```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 display the error icon and tooltip in the number column in addition to the field level message, also include the `title` and `messages` properties.
+
+#### Display Errors for the Table
+
+To display 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 2 amount must be number',
-                        'Row 2 email is invalid'
+                        '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 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.
+
+```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.
@@ -1254,13 +1471,23 @@ This example displays three lines of text and hides the rest; the text on line 3
 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. The label toggles the action mode when you press the Enter key or Space Bar. It toggles back to navigation mode when you press the Esc key twice to return focus to the cell. The component also announces the column width during a resize.
 
 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. 
+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.
 
 | Attribute        | Type              | Description                                                                                                                                        |
 | ---------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -1268,7 +1495,7 @@ Use the following `aria` attributes on `lightning-datatable` to provide a captio
 | 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`. 
+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).
 
@@ -1320,11 +1547,12 @@ If you have descriptions on an element or on multiple elements for the table, se
 
 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. Use the arrow keys to move around the
-table.
+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 the Enter key or Space Bar. You can navigate to each actionable element in the table using the Tab key.
 
+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).
+
 Columns can be resized in action mode. First, navigate to the 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
@@ -1337,9 +1565,39 @@ When focus is on a cell that contains a link, pressing enter to navigate to
 the link is currently not supported. This limitation applies to cells that
 contain data of type url, phone, and email.
 
-On custom data types, accessibility and keyboard navigation are currently not supported
-because they require DOM manipulation, which Lightning Locker prevents in custom components.
-For more information, see [Security with Lightning Locker](https://developer.salesforce.com/docs/platform/lwc/guide/security-locker-service).
+##### 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
+ <lightning-datatable
+    lwc:ref="dt"
+    key-field="id"
+    data={data}
+    columns={columns}></lightning-datatable>
+<lightning-button 
+    label="Focus" 
+    onclick={handleFocus}></lightning-button>
+```
+
+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
 

package/src/lightning/datatable/__docs__/multi-column-sorting.md

@@ -0,0 +1,113 @@
+# Multi-Column Sorting in Lightning Datatable
+
+This document details the multi-column sorting feature, which is available for INTERNAL USE ONLY as of release 250.
+
+## Overview
+
+Multi-column sorting allows users to sort data in a datatable based on multiple columns simultaneously. This feature enhances data analysis and improves user experience by providing more granular control over data organization. Users can sort data in either ascending or descending order for each column.
+
+## Implementation
+
+Multi-column sorting uses the same pattern as single-column sorting with some additional necessary attributes. Detailed instructions and examples for single-column sorting can be found in the [developer documents](https://developer.salesforce.com/docs/component-library/bundle/lightning-datatable/example).
+
+Changes to specific attributes of `lightning-datatable` enable developers to use multi-column sorting. These changes include:
+
+-   `sorted-by`: Accepts either a single column's `fieldName` or an array of `fieldNames`.
+-   `sorted-direction`: Accepts either a single value of 'asc' or 'desc' or an array of such values.
+
+The nth value in the `sorted-direction` array represents the sorting direction of the nth column listed in the `sorted-by` array. For example, a `sorted-direction` array may look like `['asc', 'desc', 'asc']` and its `sorted-by` array may be `['age', 'weight', 'height']`. In this case, `age` is sorted ascending, `weight` is sorted descending, and `height` is sorted ascending.
+
+Since these attributes now accept array values, an appropriate `onsort` event handler should be created for the `lightning-datatable` to accommodate this. The important part here is to ensure `this.sortDirection` and `this.sortedBy` are set to valid array values. Here is an example:
+
+```js
+onHandleSort(event) {
+    const {
+        sortDirections,
+        fieldNames,
+        isMultiColumnSort,
+    } = event.detail;
+
+    if (isMultiColumnSort) {
+        const cloneData = [...this.data];
+
+        // Iterate over each field and sort direction
+        fieldNames.forEach((field, index) => {
+            cloneData.sort(
+                this.sortBy(field, sortDirections[index] === 'asc' ? 1 : -1)
+            );
+        });
+
+        this.data = cloneData;
+        this.sortDirection = sortDirections;
+        this.sortedBy = fieldNames;
+    } else {
+        // Handle case where isMultiColumnSort is false
+        // (You can choose to throw an error or leave this block empty)
+        console.warn('Single column sorting is not supported.');
+    }
+}
+```
+
+Multi-column sorting can be accessed either directly within the datatable or configured to launch from a button outside of the datatable.
+
+To access multi-column sort from within the datatable itself, add the following attributes to lightning-datatable:
+
+-   `render-mode`: Multi-column sorting is available for `role-based` and `role-based-inline` modes.
+-   `show-actions-menu`: Displays a button menu in the top-right corner of the datatable, where multi-column sorting rules can be configured through a modal.
+
+The `lightning-datatable` markup for multi-column sorting should look like this:
+
+```html
+<lightning-datatable
+    key-field="id"
+    columns="{columns}"
+    data="{data}"
+    default-sort-direction="{defaultSortDirection}"
+    sorted-direction="{sortDirection}"
+    sorted-by="{sortedBy}"
+    onsort="{onHandleSort}"
+    render-mode="role-based"
+    show-actions-menu
+>
+</lightning-datatable>
+```
+
+The `show-actions-menu` attribute enables users to access a multi-column sorting modal for configuring sorting rules in a datatable's header. This sorting modal is implemented as a stand-alone component: `lightning-multi-column-sorting-modal`. Consequently, it can be triggered by a button outside of the associated `lightning-datatable`.
+
+To integrate the sorting modal with a button, follow these steps:
+
+1. Import the `lightning/multiColumnSortingModal` component into the file.
+2. Use the `onclick` handler of the button to open the sorting modal. Ensure to pass the `dtInstance` argument to reference your datatable instance:
+    ```js
+    MultiColumnSortingModal.open({
+        size: 'small',
+        dtInstance: this.template.querySelector('lightning-datatable'),
+    });
+    ```
+
+The `lightning-multi-column-sorting-modal` component supports three optional attributes for dynamically rendering and interacting with a custom component inside the `modal-body`.
+
+1. `dynamicCmp` – A Lightning Web Component (LWC) that will be rendered at the bottom of the `lightning-modal-body`.
+2. `dynamicCmpEvents` – An object defining event listeners to be attached to the `dynamicCmp`.
+3. `dynamicCmpAttributes` – An object specifying attributes to be passed to the `dynamicCmp`.
+
+Setting these attributes can easily be done, when implementing the sorting modal with a button:
+
+```js
+import CustomComp from `namespace/customComp`;
+
+MultiColumnSortingModal.open({
+    size: 'small',
+    dtInstance: this.template.querySelector('lightning-datatable'),
+    dynamicCmp: CustomComp,
+    dynamicCmpAttributes: {
+        label: 'custom label'
+        variant: 'base'
+    },
+    dynamicCmpEvents: {
+        change: this.handleChange.bind(this)
+    }
+});
+```
+
+This setup renders `CustomComp` at the bottom of the `modal-body`, sets its attributes (`label` and `variant`), and binds the `change` event handler. Note that the `dynamicCmp` should define fallback values for its attributes due to timing issues when setting `dynamicCmpAttributes`.

package/src/lightning/datatable/__examples__/basic/basic.js

@@ -1,3 +1,8 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
 import { LightningElement } from 'lwc';
 import generateData from './generateData';