--- title: Visualizing Data in VS Code sidebar_label: Visual Studio Code description: View Excel files directly in VS Code. Seamlessly browse spreadsheet data using SheetJS. Navigate between worksheets and pages of data with a responsive interface. pagination_prev: demos/cloud/index pagination_next: demos/bigdata/index sidebar_custom_props: summary: View Excel spreadsheets directly within Visual Studio Code --- import current from '/version.js'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock'; [SheetJS](https://sheetjs.com) is a JavaScript library for reading and writing data from spreadsheets. [Visual Studio Code](https://code.visualstudio.com) is a popular code editor that supports JavaScript extensions for customizing and enhancing functionality. The ["Complete Example"](#complete-example) uses SheetJS in a VS Code extension to view Excel files directly within the editor. The extension leverages the VS Code "WebView API"[^1] and "Custom Editor API"[^2] to display spreadsheet data as HTML tables. :::tip pass "SheetJS Spreadsheet Viewer" is a sample extension based on this demo. It is available on [Open VSX](https://open-vsx.org/extension/asadbek/sheetjs-demo) and [VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=asadbek.sheetjs-demo) [The source code](https://git.sheetjs.com/asadbek064/sheetjs-vscode-extension) is available on the SheetJS Git server. Feedback and contributions are welcome! ::: ![Expected output](pathname:///vscode/extension-viewing-xls-file.png) :::note Tested Deployments This demo was tested in the following deployments: | Platform | Architecture | Date | |:--------------------------------------------------|:-------------|:-----------| | [VSCodium 1.109.51242](https://vscodium.com/) | `darwin-arm` | 2026-03-05 | | [VS Code 1.110.0](https://code.visualstudio.com/) | `win11-arm` | 2026-03-05 | | [Antigravity 1.19.6](https://antigravity.google/) | `linux-arm` | 2026-03-05 | ::: :::danger Telemetry and Data Exfiltration VSCode and many forks embed telemetry and send code to third-party servers. For example, Antigravity includes AI features that are powered by Google Gemini and other cloud AI services. These features necessitate code exfiltration. **[VSCodium](https://vscodium.com/) does not include AI features or telemetry!** ::: ## Integration Details The [SheetJS NodeJS Module](/docs/getting-started/installation/nodejs) can be imported from any script in the extension. :::caution pass The SheetJS NodeJS module must be installed as a development dependency. If the module is installed as a normal dependency, the `vsce`[^3] command-line tool will fail to package or publish the extension. {`\ npm rm --save xlsx npm i --save-dev https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`} {`\ pnpm rm xlsx pnpm install -D https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`} {`\ yarn remove xlsx yarn add -D https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`} ::: The core extension APIs are available in the `vscode` package. A TypeScript extension typically uses "glob imports" to load SheetJS and VSCode features: ```ts title="Importing SheetJS and VSCode features" import * as vscode from 'vscode'; import * as XLSX from 'xlsx'; ``` ## Extension Architecture VSCode Extensions for processing custom file types use the Custom Editor API[^2] for lifecycle events. This involves a number of moving parts: 1) "Custom Document" for managing file metadata 2) "Custom Editor Provider" for processing file data and generating previews 3) Registration during extension lifecycle events. 4) Advertisement of filetype support in extension metadata. When a spreadsheet is opened, the extension will use SheetJS methods to parse the raw file and display the data in a HTML table. ### Custom Documents Extensions must provide a class that implements `vscode.CustomDocument`[^4]. ```ts title="Simple CustomDocument" class ExcelDocument implements vscode.CustomDocument { constructor(public readonly uri: vscode.Uri) { } dispose() { } } ``` ### Editor Provider Extensions that read data should implement `vscode.CustomReadonlyEditorProvider` with a generic parameter for the custom document type. The `openCustomDocument` method takes a `vscode.Uri` and is expected to return a new document: ```ts title="src/extension.ts (snippet)" class ExcelEditorProvider implements vscode.CustomReadonlyEditorProvider { async openCustomDocument(uri: vscode.Uri): Promise { return new ExcelDocument(uri); } } ``` ### Reading Files The `FileSystemProvider` API[^5], available at `vscode.workspace.fs`, exposes common filesystem operations including reading raw data from files and watching for changes. The `resolveCustomEditor`[^6] method of the `CustomEditorProvider` will be called when a file is opened. The first argument is a `CustomDocument` whose `uri` property points to the location of the file. `vscode.workspace.fs.readFile`[^5] returns a promise that resolves to a `Uint8Array` containing the raw binary data. This `Uint8Array` can be passed to the SheetJS [`read`](/docs/api/parse-options) method: ```ts title="src/extension.ts (snippet)" export class ExcelEditorProvider implements vscode.CustomReadonlyEditorProvider { // ... async resolveCustomEditor(document: ExcelDocument, webviewPanel: vscode.WebviewPanel): Promise { // read the raw bytes from the file const data: Uint8Array = await vscode.workspace.fs.readFile(document.uri); // parse the file data const wb: XLSX.WorkBook = XLSX.read(data); // At this point, `wb` is a SheetJS Workbook Object // ... } // ... } ``` ### Previewing Data The `resolveCustomEditor`[^6] method of the `CustomEditorProvider` will be called when a file is opened. The second argument is a `WebviewPanel`[^7]. The `webview.html` nested property of the `WebviewPanel` controls the displayed HTML. Extensions can use SheetJS [API methods](/docs/api/). The SheetJS [`sheet_to_html`](/docs/api/utilities/html#html-table-output) method generates a simple HTML table. The following snippet displays the data of the first worksheet: ```ts title="src/extension.ts (snippet)" export class ExcelEditorProvider implements vscode.CustomReadonlyEditorProvider { // ... async resolveCustomEditor(document: ExcelDocument, webviewPanel: vscode.WebviewPanel): Promise { // ... // continuing from "Reading Files", `wb` is a SheetJS Workbook Object const first_sheet = wb.Sheets[wb.SheetNames[0]]; webviewPanel.webview.html = XLSX.utils.sheet_to_html(first_sheet); } // ... } ``` ### Registration The exported `activate` method registers the editor provider. The first argument to `registerCustomEditorProvider` is expected to be a unique name that will be referenced later. ```ts title="src/extension.ts (snippet)" export function activate(context: vscode.ExtensionContext) { const provider = vscode.window.registerCustomEditorProvider( 'excelViewer.spreadsheet', new ExcelEditorProvider(), { webviewOptions: { retainContextWhenHidden: true } } // keep webview state when hidden ); context.subscriptions.push(provider); } ``` ### Filetype Support Extensions must announce custom editor file type support in `package.json`. The `selector` property[^8] is expected to include "Glob Pattterns"[^9]. The demo uses the following `package.json` snippet to announce support for `xls` and `xlsx` spreadsheets: ```json title="package.json (snippet)" "contributes": { "customEditors": [ { // ... other properties including displayName // highlight-start // The viewType must match the first argument of `registerCustomEditorProvider` "viewType": "excelViewer.spreadsheet", "selector": [ { "filenamePattern": "*.xlsx" }, { "filenamePattern": "*.xls" } ] // highlight-end } ], // ... }, ``` ### Usage Flow ```mermaid sequenceDiagram actor User participant VSCode as VS Code participant Provider as ExcelEditorProvider participant SheetJS participant WebView User->>VSCode: Open .xlsx file VSCode->>Provider: openCustomDocument(uri) Provider-->>VSCode: return ExcelDocument VSCode->>Provider: resolveCustomEditor(document, webviewPanel) Provider->>VSCode: workspace.fs.readFile(document.uri) VSCode-->>Provider: return file data Provider->>SheetJS: XLSX.read(data, options) SheetJS-->>Provider: return workbook Provider->>SheetJS: XLSX.utils.sheet_to_html(sheet) SheetJS-->>Provider: return HTML Provider->>WebView: set webview.html WebView-->>User: Display Excel data ``` ## Complete Example :::caution pass To avoid conflicts with existing extensions, it is strongly recommended to test with a different VSCode fork. For example, VSCode and Antigravity users should install and use VSCodium for extension development. ::: 1) Download the [`pres.xlsx`](https://docs.sheetjs.com/pres.xlsx) sample file. 2) Create a new VS Code extension ```bash npx --package yo --package generator-code -- yo code ``` When prompted, enter the following options: - `What type of extension do you want to create?`: Select `New Extension (TypeScript)` and press Enter - `What's the name of your extension?`: Type `sheetjs-demo` and press Enter - `What's the identifier of your extension?`: Press Enter (use the default `sheetjs-demo`) - `What's the description of your extension?`: Press Enter (leave blank) - `Initialize a git repository?`: Type `n` and press Enter - `Which bundler to use?`: Select `webpack` and press Enter - `Which package manager to use?`: Select `pnpm` and press Enter ![Expected output](pathname:///vscode/yeo-code.png) 3) Install the SheetJS library and start the dev server: {`\ cd sheetjs-demo pnpm install -D https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz pnpm run watch `} 4) Launch a new window with the VSCode fork and open the `sheetjs-demo` folder. 5) Save the following codeblock to `src/extension.ts`: ```ts title="src/extension.ts (replace contents)" import * as vscode from 'vscode'; import * as XLSX from 'xlsx'; class ExcelDocument implements vscode.CustomDocument { constructor(public readonly uri: vscode.Uri) { } dispose() { } } class ExcelEditorProvider implements vscode.CustomReadonlyEditorProvider { // This is called when the first time an editor for a given resource is opened async openCustomDocument(uri: vscode.Uri): Promise { return new ExcelDocument(uri); } // This is called whenever the user opens a new editor async resolveCustomEditor(document: ExcelDocument, webviewPanel: vscode.WebviewPanel): Promise { const data: Uint8Array = await vscode.workspace.fs.readFile(document.uri); const options: XLSX.ParsingOptions = { cellStyles: true, cellDates: true }; const wb: XLSX.WorkBook = XLSX.read(data, options); const first_sheet = wb.Sheets[wb.SheetNames[0]]; webviewPanel.webview.html = XLSX.utils.sheet_to_html(first_sheet); } } export function activate(context: vscode.ExtensionContext) { const provider = vscode.window.registerCustomEditorProvider( 'excelViewer.spreadsheet', new ExcelEditorProvider(), { webviewOptions: { retainContextWhenHidden: true } } // keep webview state when hidden ); context.subscriptions.push(provider); } export function deactivate() {} ``` 6) Add the highlighted lines to the `contributes` section of `package.json`: ```json title="package.json (add highlighted lines)" "contributes": { // highlight-start "customEditors": [ { "viewType": "excelViewer.spreadsheet", "displayName": "SheetJS Demo", "selector": [ { "filenamePattern": "*.xlsx" }, { "filenamePattern": "*.xls" } ] } ], // highlight-end "commands": [ { "command": "sheetjs-demo.helloWorld", "title": "Hello World" } ] }, ``` 7) In the editor, open the Command Palette (Help > "Show All Commands" from the menu), type `Debug: Start` and select `Debug: Start Debugging`. This will compile and run the extension in a new Extension Development Host window. 8) Drag and drop the `pres.xlsx` test file into the new window. If drag and drop is not available, click "Open..." in the Welcome screen and select the file. A new `pres.xlsx` tab will show the contents of the file. :::info pass When this demo was last tested, the default project assumed VSCode version 1.109.0 or later. Antigravity 1.19.6 is aligned to VSCode 1.107.0. The default extension will not run in Antigravity. This can be fixed by changing the `vscode` field in `package.json`. When this demo was last tested, it was safe to set a minimum version of `^1.100.0`: ```json title="package.json (change highlighted line)" "engines": { // highlight-next-line "vscode": "^1.100.0" } ``` ::: [^1]: See [`Webview API`](https://code.visualstudio.com/api/extension-guides/webview) in the VSCode documentation for more details. [^2]: See [`Custom Editor API`](https://code.visualstudio.com/api/extension-guides/custom-editors) in the VSCode documentation for more details. [^3]: See [`vsce`](https://code.visualstudio.com/api/working-with-extensions/publishing-extension#vsce) in the VSCode documentation for more details. [^4]: See [`CustomDocument`](https://code.visualstudio.com/api/references/vscode-api#CustomDocument) in the VSCode API documentation for more details. [^5]: See [`FileSystemProvider`](https://code.visualstudio.com/api/references/vscode-api#FileSystemProvider) in the VSCode API documentation for more details. [^6]: See [`CustomEditorProvider`](https://code.visualstudio.com/api/references/vscode-api#CustomEditorProvider<T>) in the VSCode API documentation for more details. [^7]: See [`WebviewPanel`](https://code.visualstudio.com/api/references/vscode-api#WebviewPanel) in the VSCode API documentation for more details. [^8]: See [`contributes.customEditors`](https://code.visualstudio.com/api/references/contribution-points#contributes.customEditors) in the VSCode API documentation for more details. [^9]: See ["Glob Patterns Reference"](https://code.visualstudio.com/docs/editor/glob-patterns) in the VSCode documentation for more details.