---
title: CSV files
description: The {csv-include} directive allows you to include and render CSV files as formatted tables in your documentation. The directive automatically parses CSV...
url: https://docs-v3-preview.elastic.dev/docs-builder/syntax/csv-include
---

# CSV files
The `{csv-include}` directive allows you to include and render CSV files as formatted tables in your documentation. The directive automatically parses CSV content and renders it using the standard table styles defined in `table.css`.

## Usage

<tab-set>
  <tab-item title="Output">
    **Sample user data from the database**

    | Name           | Age | City          | Occupation        |
    |----------------|-----|---------------|-------------------|
    | John Doe       | 30  | New York      | Software Engineer |
    | Jane Smith     | 25  | Los Angeles   | Product Manager   |
    | Bob Johnson    | 35  | Chicago       | Data Scientist    |
    | Alice Brown    | 28  | San Francisco | UX Designer       |
    | Charlie Wilson | 32  | Boston        | DevOps Engineer   |
  </tab-item>

  <tab-item title="Markdown">
    ```markdown
    :::{csv-include} _snippets/sample-data.csv
    :::
    ```
  </tab-item>
</tab-set>


## Options

The CSV file directive supports several options to customize the table rendering:

### Caption

Add a descriptive caption above the table:
```markdown
:::{csv-include} _snippets/sample-data.csv
:caption: Sample user data from the database
:::
```


### Custom separator

Specify a custom field separator (default is comma):
```markdown
:::{csv-include} _snippets/sample-data.csv
:separator: ;
:::
```


### Wide tables

CSV files with many columns are rendered as scrollable tables:
<tab-set>
  <tab-item title="Output">
    **Product inventory with 12 columns**

    | Product             | SKU    | Category    | Brand       | Price   | Stock | Weight | Rating | Reviews | Color  | Size     | Material    |
    |---------------------|--------|-------------|-------------|---------|-------|--------|--------|---------|--------|----------|-------------|
    | Laptop Pro          | LP-001 | Electronics | TechCorp    | 1299.99 | 45    | 2.3kg  | 4.5    | 1250    | Silver | 15 inch  | Aluminum    |
    | Wireless Mouse      | WM-002 | Accessories | ClickMaster | 49.99   | 230   | 0.1kg  | 4.2    | 890     | Black  | Standard | Plastic     |
    | USB-C Hub           | UH-003 | Accessories | ConnectAll  | 79.99   | 180   | 0.2kg  | 4.7    | 654     | Gray   | Compact  | Metal       |
    | Mechanical Keyboard | MK-004 | Accessories | TypeFast    | 159.99  | 92    | 0.8kg  | 4.8    | 2100    | White  | Full     | ABS Plastic |
    | Monitor Stand       | MS-005 | Furniture   | DeskPro     | 89.99   | 67    | 1.5kg  | 4.1    | 445     | Black  | Large    | Steel       |
  </tab-item>

  <tab-item title="Markdown">
    ```markdown
    :::{csv-include} _snippets/sample-data-12-columns.csv
    :caption: Product inventory with 12 columns
    :::
    ```
  </tab-item>
</tab-set>


### Performance limits

The directive includes built-in performance limits to handle large files efficiently:
- **Row limit**: Maximum of 25,000 rows will be displayed
- **Column limit**: Maximum of 15 columns will be displayed
- **File size limit**: Maximum file size of 10MB


### Markdown rendering in cells

Cells are parsed as Markdown, so they can render inline formatting and links. For example, a cell containing `**Bold**` becomes bold text, and `[Text](https://www.google.com)` becomes a link.
Here is a complete example that uses multiple Markdown formats:
<tab-set>
  <tab-item title="Output">
    **Sample data with Markdown formatting**

    | Name    | Notes                                              | Links                                                                     |
    |---------|----------------------------------------------------|---------------------------------------------------------------------------|
    | Alpha   | **Bold** text, _italic_ text, and `code`.          | [Google](https://www.google.com)                                          |
    | Bravo   | Inline role: {kbd}`Ctrl+C`.                        | [Elastic docs](https://www.elastic.co/docs)                               |
    | Charlie | Mixed **bold** and _italic_, plus `inline code`.   | [Search](https://www.elastic.co/docs/solutions/search)                    |
    | Delta   | Feature {applies_to}`stack: ga 9.1` available now. | [Elastic](https://www.elastic.co)                                         |
    | Echo    | This is {preview}`9.1` functionality.              | [Preview docs](https://www.elastic.co/docs)                               |
    | Foxtrot | Multiple lines using HTML breaks.                  | [Link A](https://www.elastic.co)<br>[Link B](https://www.elastic.co/docs) |
  </tab-item>

  <tab-item title="Markdown">
    ```markdown
    :::{csv-include} _snippets/sample-data-markdown.csv
    :caption: Sample data with Markdown formatting
    :::
    ```
  </tab-item>
</tab-set>


## Performance considerations

The CSV directive is optimized for large files:
- Files are processed using streaming to avoid loading everything into memory
- Built-in size validation prevents processing of files that exceed 10MB
- Row and column limits protect against accidentally rendering massive tables
- Warning messages are displayed when limits are exceeded

For optimal performance with large CSV files, consider:
- Breaking very large files into smaller, more manageable chunks