API
KViewerTabs
API reference for the KViewerTabs component
KViewerTabs manages multiple PDF documents in a tabbed interface. Each tab runs its own KViewer instance with independent state.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
items | ViewerTabItem[] | required | Initial set of document tabs |
defaultActiveTab | string | First item's ID | ID of the initially active tab |
stamps | StampDefinition[] | undefined | Forwarded to all viewer instances |
userName | string | undefined | Forwarded to all viewer instances |
signatureHandlers | SignatureHandlers | undefined | Forwarded to all viewer instances |
textLayer | boolean | false | Forwarded to all viewer instances |
readonly | boolean | false | View-only mode for all viewers |
shapeDetection | boolean | false | Can be overridden per tab via ViewerTabItem.shapeDetection |
viewMode | ViewMode | 'fit-width' | Default for tabs without a per-tab override |
zoom | number | 1 | Default for tabs without a per-tab override |
minTabs | number | 0 | Minimum number of tabs -- prevents closing below this count |
Slots
| Slot | Scope | Description |
|---|---|---|
tabs-leading | -- | Content before the tab list |
tabs-trailing | -- | Content after the tab list (e.g., "add" button) |
header | { tab: ViewerTabItem } | Custom header for each viewer |
footer | { tab: ViewerTabItem } | Custom footer for each viewer |
empty | -- | Shown when all tabs are closed |
Events
| Event | Payload | Description |
|---|---|---|
update:activeTab | string | Fired when the active tab changes |
tab-added | ViewerTabItem | Fired when a new tab is created |
tab-close | string | Fired before a tab is removed |
tab-removed | string | Fired after a tab is removed |
Methods
Access through a template ref:
<template>
<KViewerTabs ref="viewerTabs" :items="tabs" />
</template>
<script setup lang="ts">
const viewerTabs = ref()
</script>
addTab(item, options?)
Adds a new tab. Returns the tab's ID.
const tabId = viewerTabs.value?.addTab(
{
id: 'new-doc', // optional -- auto-generated if omitted
label: 'New.pdf',
source: pdfBytes,
icon: 'i-lucide-file-plus',
closable: true,
},
{
index: 0, // insert position (default: end)
activate: true, // switch to new tab (default: true)
},
)
removeTab(id)
Removes a tab by ID. Returns true if the tab was found and removed.
viewerTabs.value?.removeTab('new-doc')
activateTab(id)
Switches to the specified tab.
viewerTabs.value?.activateTab('contract')
getViewer(id)
Returns the underlying KViewer component instance for a tab, or null if the tab is not active.
const viewer = viewerTabs.value?.getViewer('contract')
const annotations = viewer?.getAnnotations()
const bytes = await viewer?.exportPdf({ flatten: true })
getViewer() only returns the instance for the currently active tab since inactive tabs are not rendered.Properties
| Property | Type | Description |
|---|---|---|
activeTabId | string | ID of the currently active tab |
tabs | ViewerTabItem[] | Current list of all tabs |
Usage Example
pages/documents.vue
<template>
<div class="h-screen">
<KViewerTabs
ref="viewerTabs"
:items="initialTabs"
:stamps="stamps"
view-mode="fit-page"
:min-tabs="0"
>
<template #tabs-trailing>
<button
class="px-2 text-sm"
@click="onAddTab"
>
+ Add
</button>
</template>
<template #empty>
<div class="flex flex-col items-center justify-center h-full gap-3">
<p>No documents open.</p>
<button @click="onAddTab">Open a document</button>
</div>
</template>
</KViewerTabs>
</div>
</template>
<script setup lang="ts">
const viewerTabs = ref()
const initialTabs = [
{ id: 'sample', label: 'Sample.pdf', source: '/sample.pdf' },
{ id: 'form', label: 'Form.pdf', source: '/Form.pdf', shapeDetection: true },
]
const stamps = [
{ id: 'check', name: 'Check', imageUrl: '/stamps/check.svg', width: 16, height: 16 },
{ id: 'cross', name: 'Cross', imageUrl: '/stamps/cross.svg', width: 16, height: 16 },
]
function onAddTab() {
const input = document.createElement('input')
input.type = 'file'
input.accept = '.pdf'
input.onchange = async () => {
const file = input.files?.[0]
if (!file) return
const source = new Uint8Array(await file.arrayBuffer())
viewerTabs.value?.addTab({ label: file.name, source })
}
input.click()
}
</script>