Class VisioDocument

The root object for reading and writing Visio (.vsdx) files.

Create a blank document with VisioDocument.create or load an existing file with VisioDocument.load. Call VisioDocument.save when done.

Example

import { VisioDocument } from 'ts-visio';

const doc  = await VisioDocument.create();
const page = doc.pages[0];
await page.addShape({ text: 'Hello, Visio!', x: 1, y: 1, width: 3, height: 1 });
await doc.save('output.vsdx');

Accessors

Methods

addBackgroundPage

addBackgroundPage(name: string): Promise<Page>
Add a background page to the document
Parameters
- name: string
Returns Promise<Page>
- Defined in VisioDocument.ts:108

addColor

addColor(hex: string): number
Add a color to the document-level color palette and return its integer index (IX).

If the color is already registered the existing index is returned without creating a duplicate. The two built-in colors are always present:
- index 0 → #000000 (black)
- index 1 → #FFFFFF (white)
User colors receive indices starting at 2.
Parameters
- hex: string
  CSS hex string — '#4472C4', '#ABC', or '4472c4' are all accepted.
Returns number
Integer IX that uniquely identifies this color in the palette.
Example
```
const blueIx = doc.addColor('#4472C4');  // → 2
const redIx  = doc.addColor('#FF0000');  // → 3
doc.addColor('#4472C4');                 // → 2 (de-duplicated)
```
- Defined in VisioDocument.ts:250

addPage

addPage(name: string): Promise<Page>
Parameters
- name: string
Returns Promise<Page>
- Defined in VisioDocument.ts:69

createMaster

createMaster(name: string, geometry?: ShapeGeometry): MasterRecord
Define a new master shape in the document and return its record. Creates all necessary OPC infrastructure (masters.xml, content-type overrides, and document-level relationships) on the first call.
Parameters
- name: string
  Display name shown in the stencil panel.
- geometry: ShapeGeometry = 'rectangle'
  Visual outline; defaults to 'rectangle'.
Returns MasterRecord
Example
```
const boxMaster = doc.createMaster('Box');
const ellMaster = doc.createMaster('Process', 'ellipse');
await page.addShape({ text: 'Start', x: 1, y: 1, width: 2, height: 1, masterId: ellMaster.id });
```
- Defined in VisioDocument.ts:309

createStyle

createStyle(name: string, props?: StyleProps): StyleRecord
Create a named document-level stylesheet and return its record. The returned id can be passed to addShape({ styleId }) or shape.applyStyle().
Parameters
- name: string
- props: StyleProps = {}
Returns StyleRecord
Example
```
const s = doc.createStyle('Header', { fillColor: '#4472C4', fontColor: '#ffffff', bold: true });
const shape = await page.addShape({ text: 'Title', x: 1, y: 1, width: 3, height: 1, styleId: s.id });
```
- Defined in VisioDocument.ts:221

deletePage

deletePage(page: Page): Promise<void>
Delete a page from the document. Removes the page XML, its relationships, the Content Types entry, and any BackPage references from other pages.
Parameters
- page: Page
Returns Promise<void>
- Defined in VisioDocument.ts:143

duplicatePage

duplicatePage(page: Page, newName?: string): Promise<Page>
Duplicate a page and return the new Page object. The duplicate is inserted directly after the source page in the tab order. If newName is omitted, "<original name> (Copy)" is used.
Parameters
- page: Page
- OptionalnewName: string
Returns Promise<Page>
Example
```
const copy = await doc.duplicatePage(page, 'Page 2');
```
- Defined in VisioDocument.ts:179

getColorIndex

getColorIndex(hex: string): number | undefined
Look up the palette index of a color by its hex value. Returns undefined if the color has not been added to the palette.
Parameters
- hex: string
Returns number | undefined
Example
```
doc.addColor('#4472C4');
doc.getColorIndex('#4472C4');  // → 2
doc.getColorIndex('#FF0000');  // → undefined
```
- Defined in VisioDocument.ts:275

getColors

getColors(): ColorEntry[]
Return all color entries in the document palette, ordered by index.

Returns ColorEntry[]
Example
```
doc.addColor('#4472C4');
doc.getColors();
// → [{ index: 0, rgb: '#000000' }, { index: 1, rgb: '#FFFFFF' }, { index: 2, rgb: '#4472C4' }]
```
- Defined in VisioDocument.ts:262

getMasters

getMasters(): MasterRecord[]
Return all master shapes currently defined in the document. Each record's id can be passed as masterId to page.addShape().

Returns MasterRecord[]
Example
```
const masters = doc.getMasters();
const box = masters.find(m => m.name === 'Box')!;
await page.addShape({ text: '', x: 2, y: 3, width: 1, height: 1, masterId: box.id });
```
- Defined in VisioDocument.ts:292

getMetadata

getMetadata(): DocumentMetadata
Read document metadata from docProps/core.xml and docProps/app.xml. Fields not present in the file are returned as undefined.

Returns DocumentMetadata
- Defined in VisioDocument.ts:198

getPage

getPage(name: string): Page | undefined
Find a page by name. Returns undefined if no page with that name exists.
Parameters
- name: string
Returns Page | undefined
- Defined in VisioDocument.ts:134

getStyles

getStyles(): StyleRecord[]
Return all stylesheets defined in the document (including built-in styles).

Returns StyleRecord[]
- Defined in VisioDocument.ts:228

importMastersFromStencil

importMastersFromStencil(
    pathOrBuffer:
        | string
        | ArrayBuffer
        | Buffer<ArrayBufferLike>
        | Uint8Array<ArrayBufferLike>,
): Promise<MasterRecord[]>
Import all masters from a .vssx stencil file into this document. Each master is assigned a fresh ID that does not conflict with any master already present. Returns the array of imported master records.
Parameters
- pathOrBuffer: string | ArrayBuffer | Buffer<ArrayBufferLike> | Uint8Array<ArrayBufferLike>
  Filesystem path or raw buffer of the .vssx file.
Returns Promise<MasterRecord[]>
Example
```
const masters = await doc.importMastersFromStencil('./Basic_Shapes.vssx');
const arrowMaster = masters.find(m => m.name === 'Arrow');
await page.addShape({ text: '', x: 3, y: 4, width: 1, height: 0.5, masterId: arrowMaster!.id });
```
- Defined in VisioDocument.ts:325

movePage

movePage(page: Page, toIndex: number): void
Move a page to a new 0-based position in the tab order. Clamps toIndex to the valid range automatically.
Parameters
- page: Page
- toIndex: number
Returns void
Example
```
doc.movePage(page, 0);  // move to first position
```
- Defined in VisioDocument.ts:166

renamePage

renamePage(page: Page, newName: string): void
Rename a page. Updates page.name in-memory as well as the pages.xml record.
Parameters
- page: Page
- newName: string
Returns void
Example
```
doc.renamePage(page, 'Architecture Overview');
```
- Defined in VisioDocument.ts:154

save

save(filename?: string): Promise<Buffer<ArrayBufferLike>>
Parameters
- Optionalfilename: string
Returns Promise<Buffer<ArrayBufferLike>>
- Defined in VisioDocument.ts:331

setBackgroundPage

setBackgroundPage(foregroundPage: Page, backgroundPage: Page): Promise<void>
Set a background page for a foreground page
Parameters
- foregroundPage: Page
- backgroundPage: Page
Returns Promise<void>
- Defined in VisioDocument.ts:126

setMetadata

setMetadata(props: Partial<DocumentMetadata>): void
Write document metadata. Only the supplied fields are changed; all other fields keep their existing values.
Parameters
- props: Partial<DocumentMetadata>
Returns void
Example
```
doc.setMetadata({ title: 'My Diagram', author: 'Alice', company: 'ACME' });
```
- Defined in VisioDocument.ts:209

`Static`create

create(): Promise<VisioDocument>
Returns Promise<VisioDocument>
- Defined in VisioDocument.ts:50

`Static`load

load(
    pathOrBuffer:
        | string
        | ArrayBuffer
        | Buffer<ArrayBufferLike>
        | Uint8Array<ArrayBufferLike>,
): Promise<VisioDocument>
Parameters
- pathOrBuffer: string | ArrayBuffer | Buffer<ArrayBufferLike> | Uint8Array<ArrayBufferLike>
Returns Promise<VisioDocument>
- Defined in VisioDocument.ts:55

Class VisioDocument

Example

Index

Accessors

Methods

Accessors

pages

Returns Page[]

Methods

addBackgroundPage

Parameters

Returns Promise<Page>

addColor

Parameters

Returns number

Example

addPage

Parameters

Returns Promise<Page>

createMaster

Parameters

Returns MasterRecord

Example

createStyle

Parameters

Returns StyleRecord

Example

deletePage

Parameters

Returns Promise<void>

duplicatePage

Parameters

Returns Promise<Page>

Example

getColorIndex

Parameters

Returns number | undefined

Example

getColors

Returns ColorEntry[]

Example

getMasters

Returns MasterRecord[]

Example

getMetadata

Returns DocumentMetadata

getPage

Parameters

Returns Page | undefined

getStyles

Returns StyleRecord[]

importMastersFromStencil

Parameters

Returns Promise<MasterRecord[]>

Example

movePage

Parameters

Returns void

Example

renamePage

Parameters

Returns void

Example

save

Parameters

Returns Promise<Buffer<ArrayBufferLike>>

setBackgroundPage

Parameters

Returns Promise<void>

setMetadata

Parameters

Returns void

Example

Staticcreate

Returns Promise<VisioDocument>

Staticload

Parameters

Returns Promise<VisioDocument>

Settings

On This Page

`Static`create

`Static`load