# gds-table

**Class**: `GdsTable`

**Tag**: `<gds-table>`


## Properties

> Some properties accept design token names. Use `get_tokens` with the appropriate category to discover valid token names and their resolved values.

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `headline` | `string \| undefined` | `-` | The main headline text displayed at the top of the table. |
| `headlineTag` | `string` | `-` | The HTML tag to use for the headline (e.g., 'h1', 'h2', etc.). |
| `summary` | `string \| undefined` | `-` | A brief description or summary displayed below the headline. |
| `searchLabel` | `string \| undefined` | `-` | The accessible label for the search input field. |
| `options` | `array` | `-` | Configurable options for rows per page. Accepts: number array (e.g., `[5, 10, 20, 50, 100]`) |
| `page` | `number` | `-` | Current page number in pagination. |
| `rows` | `number` | `-` | Number of rows displayed per page. |
| `columns` | `Types.Column[]` | `-` | Defines table column structure. Accepts: array of column configurations with keys, labels, etc. |
| `data` | `(request: Types.Request) => Promise<Types.Response<T>>` | `-` | Asynchronous data provider function. Accepts: function that returns Promise with rows and total count |
| `density` | `Types.Density` | `-` | Controls row density. Accepts: `comfortable`, `compact`, `spacious` |
| `selectable` | `boolean` | `-` | Enables row selection functionality. |
| `disableSelectAll` | `boolean` | `-` | Disables select all checkbox in header. |
| `responsive` | `boolean` | `-` | Transforms table layout for mobile screens. |
| `plain` | `boolean` | `-` | Removes table header and footer. |
| `searchable` | `boolean` | `-` | Adds search input for data filtering. |
| `settings` | `boolean` | `-` | Enables column visibility settings. |
| `striped` | `boolean` | `-` | Applies alternating row background colors. |
| `actions` | `Types.Actions \| ((row: T, index: number) => any) \| undefined` | `-` | Defines row-level actions. Accepts: action configuration or custom rendering function |
| `nocache` | `boolean` | `-` | Disables data caching mechanism. |
| `tfoot` | `Types.Tfoot \| undefined` | `-` | Configures a table footer row (`<tfoot>`) at the bottom of the table. The footer row provides slot insertion points for each visible column, letting consumers render any aggregation (sum, average, count, etc.).  Use `tfoot.label` to optionally show a label in the first cell (omitted by default). Use `tfoot.sticky` to pin the footer to the bottom of the scroll area.  Slot naming convention: `tfoot:{columnKey}`  Accepts: `{ label?: string, sticky?: boolean }` or omit to disable. |
| `dataLoadKey` | `string \| undefined` | `-` | Key to trigger data reloading when changed. Setting this to a new value forces the table to clear the cache and request new data from the data provider.  The value can be any string that is not equal to the previous value. |
| `height` | `string \| undefined` | `-` | Style Expression Property that controls the height property. Supports space tokens and all valid CSS width values.  Sets the height of the table content area and enables vertical scrolling with a sticky header that remains visible. |
| `variant` | `Omit<Variant, 'brand-01' \| 'brand-02'>` | `-` | Sets the visual variant of the table container card. Forwards to the underlying `gds-card` component. |
| `syncFirstRender` | `boolean` | `-` | Force the element to perform a synchronous first render and apply style expression properties in `connectedCallback`.  This guarantees that the child DOM always remains projected in DOM, since the element will attach the shadowRoot and run the first render pass in the same event loop cycle, and that declarative layout will be applied once slotted DOM is projected.  Note: This will cause the first render pass to be blocking. Use sparingly and only when necessary, such as when the element needs to be measured synchronously after being added to the DOM. |


## Events

| Name | Type | Description |
|------|------|-------------|
| `gds-page-change` | `CustomEvent<any>` | Fired when the active page changes. Detail: `{ page: number }` |
| `gds-rows-change` | `CustomEvent<any>` | Fired when the rows per page value changes. Detail: `{ rows: number }` |
| `gds-sort-change` | `CustomEvent<any>` | Fired when sorting changes. Detail: `{ sortColumn: string, sortDirection: 'asc' \| 'desc' }` |
| `gds-table-data-loaded` | `CustomEvent<any>` | Fired when data is successfully loaded. Detail: `{ rows: T[], total: number, page: number, rowsPerPage: number, searchQuery: string, sortColumn?: string, sortDirection?: 'asc' \| 'desc' }` |
| `gds-table-data-error` | `CustomEvent<any>` | Fired when data loading fails. |
| `gds-table-selection` | `CustomEvent<any>` | Fired when row selection changes. |


## Slots

| Name | Description |
|------|-------------|
| ``header-lead`` | Content displayed at the start of the table header (after search). |
| ``header-trail`` | Content displayed at the end of the table header (before settings). |
| ``footer`` | Content displayed in the table footer area (before pagination). |
| ``error`` | Custom error state content when data loading fails. |
| ``empty`` | Custom empty state content when no data is available. |
| ``no-results`` | Custom no results content when search returns empty. |


## Methods

### `clearSelection(): void`

Public API
Clear all selections

### `selectAll(): void`

Select all rows

### `setSelection(indices: number[]): void`

Select specific rows by indices

**Parameters:**

- `indices`: `number[]`

### `getSelection(): { indices: number[]; data: T[] }`

Get selected row data