# Import CSV

CSV import converts delimited text into new columns and rows. Unlike a transaction that appends rows, importCsvText replaces columnDefs and rowData.

Canonical: https://grid.syidax.com/docs/features/csv-import/

<a id="understand"></a>

## How it works and when to use it

First identify the header and delimiter. Design required-column validation and the business types of numeric and date strings as part of import.

In the code, grid is the Grid element prepared in the installation chapter. Check each example's data and settings, and implement the app functions and server endpoints for your project.

- [Installation and integration · Shared sample data](https://grid.syidax.com/docs/guides/getting-started.md)

<a id="example-1"></a>

## Example 1. CSV with headers

Run on a new Grid whose data may be replaced.

```javascript
const result = await grid.importCsvText('product,quantity\nAtlas,24\nBeacon,36', { hasHeader: true });
console.log(result.rowCount, result.columnCount);
```

Verify the result: Product and Quantity columns and two data rows are created. Reapply column widths and editor settings to the new columns if needed.

<a id="example-2"></a>

## Example 2. Tab-delimited files

Pass tab-delimited text copied from a spreadsheet.

```javascript
await grid.importCsvText('product\tquantity\nAtlas\t24', { delimiter: '\t', hasHeader: true });
```

Verify the result: Match the delimiter to the file format to avoid incorrectly splitting text containing commas.

<a id="example-3"></a>

## Example 3. Confirm before replacing

After file selection, show the filename, expected columns, and required-field errors first. If work already exists, finish a data snapshot or app save before replacement.

Verify the result: Read row and column counts from csvImported to explain the result. For append-only imports, build a separate flow that parses and validates rows before applyTransaction({add: …}).

<a id="pitfalls"></a>

## Combining features and troubleshooting

Importing does not save to a server. Build a separate approval or save step to persist the displayed data.

Duplicate row IDs from unvalidated imports can make later selection, editing, and comment associations unreliable.

<a id="related-api"></a>

## APIs used by this feature

- [csvImport](https://grid.syidax.com/docs/options/csvImport.md) — Provides a CSV import button and column mapping flow. Explain whether importing replaces existing columns and data.
- [importCsvText](https://grid.syidax.com/docs/methods/importCsvText.md) — Parses CSV text and replaces columns and source data. For appending rows, parse separately and use transactions.
- [csvImported](https://grid.syidax.com/docs/events/csvImported.md) — Emitted after CSV import completes. Report the actual applied row and column counts to users.

<a id="next"></a>

## Related reading

- [How rows, columns, and IDs relate](https://grid.syidax.com/docs/guides/concepts.md)
- [Connect results and events](https://grid.syidax.com/docs/guides/data-event-access.md)
- [Explore in Features](https://grid.syidax.com/grid/csv-import) — The guide describes which interactions are available to try.