﻿---
title: Tables
description: A table is an arrangement of data with rows and columns. Each row consists of cells containing arbitrary text in which inlines are parsed, separated by...
url: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2903/syntax/tables
---

# Tables
A table is an arrangement of data with rows and columns. Each row consists of cells containing arbitrary text in which inlines are parsed, separated by pipes `|`. The rows of a table consist of:
- a single header row
- a delimiter row separating the header from the data
- zero or more data rows


## Basic Table

<tab-set>
  <tab-item title="Output">
    | Country | Capital         |
    |---------|-----------------|
    | USA     | Washington D.C. |
    | Canada  | Ottawa          |
    | Mexico  | Mexico City     |
    | Brazil  | Brasília        |
    | UK      | London          |
  </tab-item>

  <tab-item title="Markdown">
    ```markdown
    | Country | Capital         |
    | ------- | --------------- |
    | USA     | Washington D.C. |
    | Canada  | Ottawa          |
    | Mexico  | Mexico City     |
    | Brazil  | Brasília        |
    | UK      | London          |
    ```
  </tab-item>
</tab-set>

<note>
  - A leading and trailing pipe is recommended for clarity of reading
  - Spaces between pipes and cell content are trimmed
  - Block-level elements cannot be inserted in a table
</note>


## Table without header

<tab-set>
  <tab-item title="Output">
    |                   |         |
    |-------------------|---------|
    | **Country**       | Austria |
    | **Capital**       | Vienna  |
    | **Calling code**  | +43     |
    | **ISO 3166 code** | AT      |
  </tab-item>

  <tab-item title="Markdown">
    ```markdown
    |                   |         |
    |-------------------|---------|
    | **Country**       | Austria |
    | **Capital**       | Vienna  |
    | **Calling code**  | +43     |
    | **ISO 3166 code** | AT      |
    ```
  </tab-item>
</tab-set>


## Responsive Table

Every table is responsive by default. The table will automatically scroll horizontally when the content is wider than the viewport.
<tab-set>
  <tab-item title="Output">
    | Product Name | Price ($) | Stock | Category  | Rating | Color  | Weight (kg) | Warranty (months) |
    |--------------|-----------|-------|-----------|--------|--------|-------------|-------------------|
    | Laptop Pro   | 1299.99   | 45    | Computer  | 4.5    | Silver | 1.8         | 24                |
    | Smart Watch  | 299.99    | 120   | Wearable  | 4.2    | Black  | 0.045       | 12                |
    | Desk Chair   | 199.50    | 78    | Furniture | 4.8    | Gray   | 12.5        | 36                |
  </tab-item>

  <tab-item title="Markdown">
    ```markdown
    | Product Name | Price ($) | Stock  | Category  | Rating  | Color    | Weight (kg) | Warranty (months) |
    |--------------|-----------|--------|-----------|---------|----------|-------------|-------------------|
    | Laptop Pro   | 1299.99   | 45     | Computer  | 4.5     | Silver   | 1.8         | 24                |
    | Smart Watch  | 299.99    | 120    | Wearable  | 4.2     | Black    | 0.045       | 12                |
    | Desk Chair   | 199.50    | 78     | Furniture | 4.8     | Gray     | 12.5        | 36                |
    ```
  </tab-item>

  ```
  ```
</tab-set>


## Table directive with column widths

The `{table}` directive wraps a pipe table and lets you control column widths using a 12-unit grid system (similar to Bootstrap). Use the `:widths:` option to specify how space is distributed across columns.

### Presets

- **`auto`** (default): Browser determines column widths based on content. Omit `:widths:` or set it to `auto`.
- **`description`**: First column 4 units, second column 8 units. Ideal for term/description tables.


### Custom widths

Use dash-separated integers that sum to 12. Each number is the grid units for that column:
- `4-8` — two columns: 33% and 67%
- `4-4-4` — three equal columns
- `3-3-3-3` — four equal columns


### Description preset (term/description)

Ideal for glossaries, API parameter tables, or key-value lists where the first column is shorter.
<tab-set>
  <tab-item title="Output">
    <table>
      | Term          | Description                                   |
      |---------------|-----------------------------------------------|
      | Elasticsearch | A distributed search and analytics engine     |
      | Kibana        | A visualization and management platform       |
      | Fleet         | A host management solution for Elastic Agent  |
      | Beats         | Lightweight data shippers for edge monitoring |
    </table>
  </tab-item>

  <tab-item title="Markdown">
    ```markdown
    :::{table}
    :widths: description

    | Term | Description |
    | --- | --- |
    | Elasticsearch | A distributed search and analytics engine |
    | Kibana | A visualization and management platform |
    | Fleet | A host management solution for Elastic Agent |
    | Beats | Lightweight data shippers for edge monitoring |
    :::
    ```
  </tab-item>
</tab-set>


### Custom widths (4-8)

Two columns with a narrow first column (33%) and wider second column (67%).
<tab-set>
  <tab-item title="Output">
    <table>
      | Parameter | Value                                          |
      |-----------|------------------------------------------------|
      | `index`   | The name of the index to search                |
      | `query`   | The query DSL defining search criteria         |
      | `size`    | Maximum number of hits to return (default: 10) |
    </table>
  </tab-item>

  <tab-item title="Markdown">
    ```markdown
    :::{table}
    :widths: 4-8

    | Parameter | Value |
    | --- | --- |
    | `index` | The name of the index to search |
    | `query` | The query DSL defining search criteria |
    | `size` | Maximum number of hits to return (default: 10) |
    :::
    ```
  </tab-item>
</tab-set>


### Three equal columns (4-4-4)

<tab-set>
  <tab-item title="Output">
    <table>
      | Product       | Version | Status  |
      |---------------|---------|---------|
      | Elasticsearch | 8.x     | Current |
      | Kibana        | 8.x     | Current |
      | Logstash      | 8.x     | Current |
    </table>
  </tab-item>

  <tab-item title="Markdown">
    ```markdown
    :::{table}
    :widths: 4-4-4

    | Product | Version | Status |
    | --- | --- | --- |
    | Elasticsearch | 8.x | Current |
    | Kibana | 8.x | Current |
    | Logstash | 8.x | Current |
    :::
    ```
  </tab-item>
</tab-set>


### Four equal columns (3-3-3-3)

<tab-set>
  <tab-item title="Output">
    <table>
      | Q1  | Q2  | Q3  | Q4  |
      |-----|-----|-----|-----|
      | 100 | 120 | 95  | 110 |
      | 200 | 180 | 220 | 195 |
    </table>
  </tab-item>

  <tab-item title="Markdown">
    ```markdown
    :::{table}
    :widths: 3-3-3-3

    | Q1 | Q2 | Q3 | Q4 |
    | --- | --- | --- | --- |
    | 100 | 120 | 95 | 110 |
    | 200 | 180 | 220 | 195 |
    :::
    ```
  </tab-item>
</tab-set>


### Asymmetric layout (2-4-6)

<tab-set>
  <tab-item title="Output">
    <table>
      | ID  | Name  | Description                          |
      |-----|-------|--------------------------------------|
      | 1   | Alpha | First item with a longer description |
      | 2   | Beta  | Second item with additional details  |
    </table>
  </tab-item>

  <tab-item title="Markdown">
    ```markdown
    :::{table}
    :widths: 2-4-6

    | ID | Name | Description |
    | --- | --- | --- |
    | 1 | Alpha | First item with a longer description |
    | 2 | Beta | Second item with additional details |
    :::
    ```
  </tab-item>
</tab-set>


### Auto preset (default)

When `:widths:` is omitted or set to `auto`, the browser determines column widths based on content. No column width constraints are applied.
<tab-set>
  <tab-item title="Output">
    <table>
      | Left | Center | Right |
      |------|--------|-------|
      | 1    | 2      | 3     |
    </table>
  </tab-item>

  <tab-item title="Markdown">
    ```markdown
    :::{table}
    :widths: auto

    | Left | Center | Right |
    | --- | --- | --- |
    | 1 | 2 | 3 |
    :::
    ```
  </tab-item>
</tab-set>


### Validation

- Widths must sum to 12.
- The number of width values must match the table column count.
- The directive must contain exactly one pipe table.