--- url: https://vue-json-excel3.netlify.app/getting-started.md description: >- Install vue-json-excel3, register the component locally or globally, and download your first Excel or CSV file. --- # Getting Started ## Installation ::: code-group ```bash [npm] npm install vue-json-excel3 ``` ```bash [pnpm] pnpm add vue-json-excel3 ``` ```bash [yarn] yarn add vue-json-excel3 ``` ```bash [bun] bun add vue-json-excel3 ``` ::: `vue` (version 3) is the only peer dependency. ## Register the component ### Locally Import it in the component that needs it: ```vue [MyComponent.vue] ``` ### Globally Or register it once in your app entry point: ```js [main.js] import { createApp } from 'vue' import JsonExcel from 'vue-json-excel3' import App from './App.vue' const app = createApp(App) app.component('downloadExcel', JsonExcel) app.mount('#app') ``` ## Use it in your template Wrap any content — text, an icon, your own button — and pass the data to export. Clicking it downloads the file. ```html Download Data ``` Set [`type`](/props) to `xlsx` or `csv` to change the file format, and use [`fields`](/simple-examples) to choose and label the columns. Every option is listed on the [Props](/props) page. ::: warning About the .xls format The default `xls` type uses an HTML table to build the file. Microsoft Excel no longer recognises HTML as native content, so it shows a warning before opening the file. The content renders correctly, but the message can't be avoided — use `type="xlsx"` to get a native workbook without the warning. ::: ## Next steps --- --- url: https://vue-json-excel3.netlify.app/props.md description: >- Every prop and event of the vue-json-excel3 component, with types and defaults. --- # Props | Name | Type | Default | Description | | :--- | :---: | :---: | --- | | `data` | `Array` | | Data to be exported. | | `fields` | `Object` | | Fields inside the JSON objects to export, as `{ 'Column label': 'path.to.value' }`. If none are provided, every property is exported. See [Callbacks](/using-callbacks-examples) for formatting. | | `export-fields` | `Object` | | Same as `fields`. Use it when another library (e.g. vee-validate) already uses a `fields` attribute. | | `type` | `String` | `xls` | File type: `xls`, `xlsx` or `csv`. | | `name` | `String` | `data.xls` | File name of the download. | | `header` | `String \| Array` | | Title row(s) above the data. A string for one title, an array of strings for several. | | `title` | `String \| Array` | | Same as `header`, kept for backwards compatibility. Avoid it: it conflicts with the HTML `title` attribute. | | `per-columns-headers` | `Array` | | One header per column, e.g. `['Col A', , 'Col C']`. | | `footer` | `String \| Array` | | Footer row(s) below the data. A string for one footer, an array of strings for several. | | `default-value` | `String` | `''` | Fallback used when a row has no value for a field. | | `worksheet` | `String` | `Sheet1` | Name of the worksheet tab. | | `meta` | `Array` | `[]` | Extra `` tags for the `xls` file, e.g. `[[{ key: 'charset', value: 'utf-8' }]]`. | | `fetch` | `Function` | | Callback that returns the data when the user clicks. Only used when no `data` is set. See [Fetch data on demand](/using-callbacks-examples#fetch-data-on-demand). | | `before-generate` | `Function` | | Called right before the data is fetched / generated, e.g. to show a loader. | | `before-finish` | `Function` | | Called right before the download dialog opens, e.g. to hide a loader. | | `formats` | `Object` | `{}` | `xlsx` only. Cell number formats keyed by column letter, e.g. `{ B: '0.00%' }`. See [Cell formats](/cell-format-xlsx-examples). | | `widths` | `Object` | `{}` | `xlsx` only. Column widths in characters keyed by column letter, e.g. `{ A: 20 }`. | | `stringify-long-num` | `Boolean` | `false` | Stringify long numbers and decimals so they don't lose precision. | | `escape-csv` | `Boolean` | `true` | Wraps every CSV value in `="` and `"` to stop Excel mangling number-like fields. Set to `false` to disable. | | `emit-blob` | `Boolean` | `false` | Emit the generated file as a `blob` event instead of downloading it. | | `debounce` | `Number` | `500` | Debounce delay (ms) of the download click. | | `rtl` | `Boolean` | `false` | Right-to-left worksheet. | ## Events | Name | Payload | Description | | :--- | :--- | --- | | `blob` | `Blob` | Emitted with the generated file when `emit-blob` is `true`. | ```vue Upload as Excel ``` --- --- url: https://vue-json-excel3.netlify.app/examples.md description: >- Live vue-json-excel3 examples with copyable source — xls, xlsx and CSV downloads, callbacks, fetching on demand, multi-line values and cell formats. --- # Examples Live demos with copyable source. Each one is a small single-file component — click the button to download a real file, or use **Show code** to copy it into your app. --- --- url: https://vue-json-excel3.netlify.app/simple-examples.md description: >- Choose which JSON fields to export, label the columns, read nested values and download an .xls file. --- # Simple Example Pass your rows to `data` and describe the columns with `fields`. Keys are the column labels, values are the (possibly nested) JSON paths to export. ```vue ``` ## Fields `fields` decides which columns are exported. Each value is exported as is, unless you give a `callback` to format it: ```js const jsonFields = { // regular field (exported as is) — nested paths are supported fieldLabel: 'attributeName', // callback for formatting anotherFieldLabel: { field: 'anotherAttributeName', // nested paths are supported callback: (value) => `formatted value ${value}`, }, } ``` If no `fields` are provided, the keys of the first object in `data` are used as the column names. You can also pass the fields inline with `export-fields`: ```vue-html ``` ## Options API Using the Options API with a globally registered component works the same way: ```js import { createApp } from 'vue' import JsonExcel from 'vue-json-excel3' createApp({ components: { downloadExcel: JsonExcel }, data() { return { json_fields: { 'Complete name': 'name', City: 'city', Telephone: 'phone.mobile' }, json_data: [ { name: 'Tony Peña', city: 'New York', phone: { mobile: '1-541-754-3010' } }, ], json_meta: [[{ key: 'charset', value: 'utf-8' }]], } }, }).mount('#app') ``` ```html Download Excel (you can customize this with html code!) ``` --- --- url: https://vue-json-excel3.netlify.app/export-csv-examples.md description: Export JSON as a CSV file by setting the type prop to csv. --- # Export CSV To export JSON as a CSV file, set the `type` prop to `"csv"`. ```vue ``` ::: tip Number-like values By default every CSV value is wrapped in `="` and `"` so Excel doesn't strip leading zeros or turn long numbers into scientific notation. Set `:escape-csv="false"` to export plain values. ::: --- --- url: https://vue-json-excel3.netlify.app/export-xlsx-examples.md description: Export JSON as a native Excel workbook by setting the type prop to xlsx. --- # Export Excel .xlsx To export JSON as a native Excel workbook, set the `type` prop to `"xlsx"`. Unlike the default `xls` type, Excel opens these files without a format warning. ```vue ``` `.xlsx` files also support [cell formats and column widths](/cell-format-xlsx-examples). --- --- url: https://vue-json-excel3.netlify.app/multi-line-examples.md description: >- Values containing newline characters stay in a single Excel cell instead of being split across rows. --- # Multi-line Values A text value that contains newline characters (`\n`) appears as a **single cell** in Excel. This avoids multi-line values being split into several cells that must be merged before you can use filters and pivot tables. ```vue ``` The result in Excel: ![Excel showing a multi-line value in a single cell](./example-multi-line.png) --- --- url: https://vue-json-excel3.netlify.app/using-callbacks-examples.md description: >- Format exported values with field callbacks, and fetch data on demand with loading hooks. --- # Using Callbacks ## Field callbacks When a field has a `callback`, there are three ways to choose what it receives: * **`field: 'path.to.nested.property'`** — a specific nested value. * **`field: 'path.to.nested.object'`** — a whole nested object. * **No `field`** — the whole row. ```vue ``` ## Fetch data on demand If the data comes from a server, use the `fetch` prop instead of `data`. The function runs when the user clicks and must return the rows to export. Pair it with `before-generate` and `before-finish` to show a loading state. ::: warning `fetch` is only used when no `data` prop is set. ::: ```vue ``` A real API call looks like this: ```js async function fetchData() { const response = await fetch('/api/holidays?country=US&year=2017') const { holidays } = await response.json() return holidays } ``` --- --- url: https://vue-json-excel3.netlify.app/cell-format-xlsx-examples.md description: >- Apply Excel number formats (currency, percentage, decimals) and column widths to .xlsx exports. --- # Cell Formats & Widths ::: warning `formats` and `widths` only work with `type="xlsx"`. ::: `formats` maps a **column letter** to an Excel number format string. `widths` maps a column letter to a width in characters (supported from **v1.0.26**). ```vue ``` ## Common formats | Format | Example output | | :--- | :--- | | `'0.00'` | `123.46` | | `'#,##0'` | `50,000` | | `'0.00%'` | `75.00%` | | `'"$"#,##0.00_);\\("$"#,##0.00\\)'` | `$50,000.00` | | `'yyyy-mm-dd'` | `2024-03-15` | --- --- url: https://vue-json-excel3.netlify.app/ai.md description: >- Give AI assistants and coding agents accurate vue-json-excel3 context with llms.txt, llms-full.txt, per-page Markdown, and ready-to-paste setups for Claude Code, Cursor, Copilot, Codex and chat assistants. --- # Use with AI These docs are built to be read by AI assistants and coding agents as well as people. Point your agent at the right source and it will write correct vue-json-excel3 code instead of guessing from outdated examples. ## Machine-readable docs | URL | What it is | | --- | --- | | [`/llms.txt`](https://vue-json-excel3.netlify.app/llms.txt) | A short index of every page with its title and description, following the [llms.txt](https://llmstxt.org/) convention. Good for agents that fetch pages on demand. | | [`/llms-full.txt`](https://vue-json-excel3.netlify.app/llms-full.txt) | The complete documentation in one Markdown file. Best for pasting into a chat or loading as context. | | Any page + `.md` | Append `.md` to any docs URL to get that page as clean Markdown, for example [`/props.md`](https://vue-json-excel3.netlify.app/props.md) or [`/using-callbacks-examples.md`](https://vue-json-excel3.netlify.app/using-callbacks-examples.md). | The Markdown versions contain the full source of every live demo and plain tables for the props, without interactive widgets. ## Copy page / Ask AI Every docs page has a **Copy page** button and an **Ask AI** menu at the top: * **Copy page** copies the current page as Markdown, ready to paste into any assistant. * **Ask AI** opens your assistant of choice (ChatGPT, Claude, Grok, Perplexity, and others) with a prompt that references the page. For DeepSeek and Gemini, which do not accept a prefilled prompt from a link, the prompt is copied to your clipboard and the site opens in a new tab: just paste. ## Claude Code Add this to your project's `CLAUDE.md`: ```md ## vue-json-excel3 This project uses vue-json-excel3 to download JSON as Excel / CSV files. When working with it, fetch https://vue-json-excel3.netlify.app/llms-full.txt for the current API instead of relying on memory. Import it as `import JsonExcel from 'vue-json-excel3'`. ``` ### Optional: a Claude Code skill For on-demand loading, create `.claude/skills/vue-json-excel3/SKILL.md`: ```md --- name: vue-json-excel3 description: Use when adding, configuring or debugging Excel / CSV downloads with the vue-json-excel3 Vue 3 component (JsonExcel, download-excel, xls, xlsx, csv export, fields, cell formats). --- # vue-json-excel3 Full docs: https://vue-json-excel3.netlify.app/llms-full.txt (fetch when unsure). Rules: - Import: `import JsonExcel from 'vue-json-excel3'`. Global: `app.component('downloadExcel', JsonExcel)`. - It is a wrapper: put any content (text, icon, button) in the default slot; clicking it builds the file in the browser and downloads it. - `type`: 'xls' (default, HTML-based, Excel shows a format warning), 'xlsx' (native workbook, no warning) or 'csv'. Set `name` with a matching extension. - `data`: array of row objects. `fields`: { 'Column label': 'path.to.value' }. Nested paths work. Without `fields`, the keys of the first row are used. Use `export-fields` when another library already uses a `fields` attribute. - Field callbacks: { field: 'path', callback: (value) => ... }. `field` can point at a nested object; omit `field` to receive the whole row. - Load data on click with `:fetch="async () => rows"` (only when no `data`), plus `before-generate` / `before-finish` for loading state. - xlsx only: `:formats="{ B: '0.00%' }"` and `:widths="{ A: 20 }"`, keyed by column letter. - Other props: header, footer, per-columns-headers, worksheet, default-value, meta, escape-csv (default true), stringify-long-num, rtl, debounce (500 ms). - `emit-blob` + `@blob` returns the file as a Blob instead of downloading it. - SSR (Nuxt/VitePress): render it inside ``. ``` ## Cursor, GitHub Copilot, OpenAI Codex, Windsurf Most coding agents read an `AGENTS.md` file at the repository root (Copilot also reads `.github/copilot-instructions.md`, Windsurf reads `.windsurfrules`). Add: ```md ## vue-json-excel3 - Docs for agents: https://vue-json-excel3.netlify.app/llms-full.txt - Per-page Markdown: append `.md` to any https://vue-json-excel3.netlify.app URL. - Import with `import JsonExcel from 'vue-json-excel3'`; wrap a button with it and pass `:data`, `:fields`, `type` ('xls' | 'xlsx' | 'csv') and `name`. - Prefer `type="xlsx"` for Excel files; `formats` / `widths` only work with xlsx. ``` **Cursor @Docs:** open *Cursor Settings → Indexing & Docs → Add Doc* and enter `https://vue-json-excel3.netlify.app/llms-full.txt`. Then reference it in chat with `@Docs vue-json-excel3`. ## ChatGPT, Claude.ai, Grok, DeepSeek, Gemini, Perplexity In any chat assistant: 1. Paste the URL `https://vue-json-excel3.netlify.app/llms-full.txt` and ask it to read it (assistants with browsing), **or** 2. Open `/llms-full.txt`, copy everything and paste it into the chat (works everywhere), **or** 3. Use the **Ask AI** menu on the page you are reading. For DeepSeek and Gemini the prompt is copied to your clipboard; paste it into the chat. ## Prompt recipes Copy and adapt these prompts: ::: details Export a table to Excel > Using vue-json-excel3 (docs: https://vue-json-excel3.netlify.app/llms-full.txt), add an "Export to Excel" button to my `` component that downloads the current rows as `users.xlsx`, with columns "Name", "Email" and "Signed up" (formatted as `yyyy-mm-dd`), and sensible column widths. > ::: ::: details Fetch from an API on click > Using vue-json-excel3, create a "Download report" button that calls `GET /api/report` only when clicked (use the `fetch` prop), shows a spinner with `before-generate` / `before-finish`, and downloads the result as CSV. > ::: ::: details Format money and percentages > Following https://vue-json-excel3.netlify.app/cell-format-xlsx-examples.md, export my `orders` array as xlsx with the total column formatted as USD currency and the discount column as a percentage. > ::: ::: details Nuxt integration > Add vue-json-excel3 to my Nuxt app: register it in a client-only plugin, render the download button inside ``, and export the data from a `useFetch` call. > :::