useTheme composable
The useTheme composable provides functions to configure the theme.
You can use the useTheme composable to configure the theme in your .vitepress/theme/index.js file, or in any .md page/file.
import { useTheme, locales } from 'vitepress-openapi/client'
export default {
async enhanceApp({app, router, siteData}) {
useTheme({
theme: {
highlighterTheme: {
light: 'vitesse-light',
dark: 'vitesse-dark',
},
},
path: {
// Show the base URL in the path component.
showBaseURL: false,
},
requestBody: {
// Set the default schema view.
defaultView: 'schema', // schema or contentType
},
jsonViewer: {
// How many levels are expanded on load.
deep: Infinity,
// Set the JSON viewer renderer.
renderer: 'vue-json-pretty', // vue-json-pretty or shiki
},
schemaViewer: {
// How many levels are expanded on load.
deep: 1,
},
// Set the heading levels.
headingLevels: {
h1: 1,
h2: 2,
h3: 3,
h4: 4,
h5: 5,
h6: 6,
},
response: {
// Set the response code selector.
responseCodeSelector: 'tabs', // tabs or select
// Set the maximum number of tabs, after which a Select will be shown.
maxTabs: 5,
body: {
// Set the default view.
defaultView: 'schema', // schema or contentType
},
},
playground: {
jsonEditor: {
// Set the mode of the JSON editor.
mode: 'tree', // text, tree, or table
// Set the visibility of the main menu bar.
mainMenuBar: false,
// Set the visibility of the navigation bar.
navigationBar: false,
// Set the visibility of the status bar.
statusBar: false,
},
examples: {
// Behavior for standard `example` / `examples` fields.
behavior: 'value', // placeholder, value, or ignore
// Behavior for `x-playground-example` extension field.
playgroundExampleBehavior: 'value', // placeholder, value, or ignore
},
},
operation: {
// Set the operation badges. The order is respected.
badges: ['deprecated'],
// Slots to render in the OAOperation component.
slots: [
'header',
'path',
'description',
'security',
'parameters',
'request-body',
'responses',
'playground',
'code-samples',
'branding',
'footer',
],
// Slots to hide in the OAOperation component.
hiddenSlots: [],
// Set the number of columns to use in the OAOperation component.
cols: 2,
// Set the default base URL.
defaultBaseUrl: 'http://localhost',
// Deprecated. Use `server.getServers` instead.
getServers: ({ method, path, operation }) => Array<string>,
},
// Set the i18n configuration.
i18n: {
locale: 'en', // en | es | ja | pt-BR | string
fallbackLocale: 'en', // en | es | ja | pt-BR | string
messages: {
en: {
...locales.en,
'operation.badgePrefix.operationId': 'Operation ID',
},
es: {
...locales.es,
'operation.badgePrefix.operationId': 'ID de operación',
},
},
availableLocales: [
{ code: 'en', label: 'English' },
{ code: 'es', label: 'Español' },
{ code: 'ja', label: 'Japanese' },
{ code: 'pt-BR', label: 'Português (Brasil)' },
{ code: 'zh', label: '中文' },
],
},
// Set spec configuration.
spec: {
groupByTags: true, // Group paths by tags.
collapsePaths: false, // Collapse paths when grouping by tags.
showPathsSummary: true, // Show a summary of the paths when grouping by tags.
avoidCirculars: false, // Avoid circular references when parsing schemas.
lazyRendering: false, // Lazy render Paths and Tags components.
defaultTag: 'Default', // Default tag to use when a path has no tags.
defaultTagDescription: '', // Description for the default tag.
wrapExamples: true, // Wrap examples in a row or show them in a column.
disableDownload: false, // Disable the download button in the info section.
},
server: {
// Set a custom function to get servers.
getServers: ({ method, path, operation }) => Array<string>,
// Allow custom servers.
allowCustomServer: true,
},
storage: {
// Set the localStorage key prefix.
prefix: '--oa',
// Set to false to disable persisting auth values to localStorage.
persistAuth: true,
},
markdown: {
operationLink: {
// Link prefix to search for operations.
linkPrefix: '/operations/',
// Transform the href of operation links.
transformHref: (href) => {
return `/example${href}`
},
},
externalLinksNewTab: true,
config: md => md,
// Sanitize HTML in Markdown descriptions (default), or pass a custom sanitizer.
sanitize: true,
},
})
}
}Utility Functions
General-purpose functions available from the composable.
| Function | Description |
|---|---|
isDark | Reactive Ref<boolean> that reflects the current VitePress dark mode. |
reset() | Resets all theme configuration back to the default values. |
getState() | Returns a deep plain object (non-reactive) snapshot of the full config. |
const { isDark, reset, getState } = useTheme()
// Reactively read dark mode
console.log(isDark.value) // true | false
// Reset all config to defaults
reset()
// Read full config as a plain object
console.log(getState())Theme / Highlighter Configuration
Configures the syntax highlighter (Shiki) theme for code blocks. You can set different themes for light and dark mode.
| Function | Description |
|---|---|
setHighlighterTheme | Sets the highlighter theme config. |
getHighlighterTheme | Returns the current theme config. |
Config shape: { light?: ShikiTheme, dark?: ShikiTheme }. Shiki theme names (e.g. from @shikijs/themes) or theme objects are supported.
useTheme({
theme: {
highlighterTheme: {
light: 'vitesse-light',
dark: 'vitesse-dark',
},
},
})Languages shipped by Shiki are loaded on demand from highlighter. For a TextMate grammar Shiki does not bundle, register it here. The same grammar object can be passed to VitePress markdown.languages; the two highlighters stay separate because samples are highlighted in the browser.
| Function | Description |
|---|---|
setShikiLanguages | Merges custom grammars into the registry. |
getShikiLanguages | Returns the registered grammars. |
getShikiLanguage | Returns one grammar by id. |
Each value can be a TextMate grammar (name, scopeName, patterns — the same shape as Shiki's LanguageRegistration), an array of them, or a loader that returns either (including { default } from import()). The object key is the id used by LanguageConfig.highlighter. If that key is not the grammar name or one of its aliases, it is added as an alias. embeddedLangs that Shiki already bundles are loaded first.
useTheme({
theme: {
shikiLanguages: {
bru: {
name: 'bru',
scopeName: 'source.bru',
patterns: [],
},
elm: () => import('./grammars/elm'),
},
},
})Path Configuration
| Function | Description | Default Value | Allowed Values |
|---|---|---|---|
setShowBaseURL | Sets whether the base URL is shown. | false | true, false |
getShowBaseURL | Gets whether the base URL is shown. | — | — |
Request Body Configuration
| Function | Description | Default Value | Allowed Values |
|---|---|---|---|
setRequestBodyDefaultView | Sets the default schema view. | 'contentType' | 'schema', 'contentType' |
getRequestBodyDefaultView | Gets the default schema view. | — | — |
JSON Viewer Configuration
| Function | Description | Default Value | Allowed Values |
|---|---|---|---|
setJsonViewerDeep | Sets the JSON viewer depth. | Infinity | number |
getJsonViewerDeep | Gets the JSON viewer depth. | — | — |
setJsonViewerRenderer | Sets the JSON viewer renderer. | 'vue-json-pretty' | 'vue-json-pretty', 'shiki' |
getJsonViewerRenderer | Gets the JSON viewer renderer. | — | — |
Schema Viewer Configuration
| Function | Description | Default Value | Allowed Values |
|---|---|---|---|
setSchemaViewerDeep | Sets the schema viewer depth. | 1 | number |
getSchemaViewerDeep | Gets the schema viewer depth. | — | — |
Heading Levels Configuration
| Function | Description | Default Value | Allowed Values |
|---|---|---|---|
setHeadingLevels | Sets the heading levels. | { h1: 1, h2: 2, h3: 3, h4: 4, h5: 5, h6: 6 } | { h1: number, h2: number, h3: number, h4: number, h5: number, h6: number } |
getHeadingLevels | Gets the full heading levels object. | — | — |
getHeadingLevel | Gets the resolved tag name for a specific level. | — | 'h1' | 'h2' | ... | 'h6' |
getHeadingLevel(level) accepts a key ('h1'–'h6') and returns the mapped HTML tag string (e.g. 'h2'). Throws if the configured value is out of range [1, 6].
const { getHeadingLevel } = useTheme()
getHeadingLevel('h1') // → 'h1' (or whatever h1 is mapped to)Response Configuration
| Function | Description | Default Value | Allowed Values |
|---|---|---|---|
setResponseCodeSelector | Sets the response code selector. | 'tabs' | 'tabs', 'select' |
getResponseCodeSelector | Gets the response code selector. | — | — |
setResponseCodeMaxTabs | Sets the maximum number of tabs, after which a Select will be shown. | 5 | number |
getResponseCodeMaxTabs | Gets the maximum number of tabs. | — | — |
setResponseBodyDefaultView | Sets the default view of the response body. | 'contentType' | 'schema', 'contentType' |
getResponseBodyDefaultView | Gets the default view of the response body. | — | — |
Playground JSON Editor Configuration
| Function | Description | Default Value | Allowed Values |
|---|---|---|---|
setPlaygroundJsonEditorMode | Sets the mode of the JSON editor. | 'tree' | 'text', 'tree', 'table' |
getPlaygroundJsonEditorMode | Gets the mode of the JSON editor. | — | — |
setPlaygroundJsonEditorMainMenuBar | Sets the visibility of the main menu bar. | false | true, false |
getPlaygroundJsonEditorMainMenuBar | Gets the visibility of the main menu bar. | — | — |
setPlaygroundJsonEditorNavigationBar | Sets the visibility of the navigation bar. | false | true, false |
getPlaygroundJsonEditorNavigationBar | Gets the visibility of the navigation bar. | — | — |
setPlaygroundJsonEditorStatusBar | Sets the visibility of the status bar. | false | true, false |
getPlaygroundJsonEditorStatusBar | Gets the visibility of the status bar. | — | — |
Playground Examples Configuration
Controls how example values from the OpenAPI spec are applied in the playground. Two sources are configured independently:
behavior— applies to standardexample/examplesfields.playgroundExampleBehavior— applies to thex-playground-exampleextension field.
See Playground Examples for details on x-playground-example.
| Function | Description | Default Value | Allowed Values |
|---|---|---|---|
setPlaygroundExamplesBehavior | Sets the behavior for standard example / examples values. | 'value' | 'placeholder', 'value', 'ignore' |
getPlaygroundExamplesBehavior | Gets the current behavior for standard examples. | — | — |
setPlaygroundXExampleBehavior | Sets the behavior for x-playground-example values. | 'value' | 'placeholder', 'value', 'ignore' |
getPlaygroundXExampleBehavior | Gets the current behavior for x-playground-example values. | — | — |
placeholder— show as placeholder text only.value— pre-fill the field with the example value.ignore— do not use the example.
useTheme({
playground: {
examples: {
behavior: 'placeholder', // for spec `example` fields
playgroundExampleBehavior: 'value', // for spec `x-playground-example` fields
},
},
})Security Configuration
Sets the default security scheme used when multiple schemes are available (e.g. in the playground).
| Function | Description | Default Value | Allowed Values |
|---|---|---|---|
setSecurityDefaultScheme | Sets the default security scheme ID. | null | string | null |
getSecurityDefaultScheme | Gets the current default scheme. | — | — |
Code Samples Configuration
Configures how code samples are generated and displayed (languages, generator, default headers).
| Function | Description |
|---|---|
setCodeSamplesConfig | Sets the full code samples config. |
getCodeSamplesDefaultLang | Gets the default language for the code samples UI. |
getCodeSamplesAvailableLanguages | Gets the list of available languages. |
getCodeSamplesGenerator | Gets the custom generator function. |
getCodeSamplesDefaultHeaders | Gets the default headers used when generating samples. |
getCodeSamplesAvailableLanguages(filter?) accepts an optional string[] to filter languages by their lang identifier.
Config shape: { defaultLang?, availableLanguages?, generator?, defaultHeaders? }.
useTheme({
codeSamples: {
defaultLang: 'curl',
availableLanguages: [
{
lang: 'curl',
label: 'cURL',
target: 'shell',
client: 'curl',
highlighter: 'bash',
icon: 'curl',
},
],
generator: async (langConfig, request) => { /* return generated code string */ },
defaultHeaders: { 'X-Custom': 'value' },
},
})Each language in availableLanguages is a LanguageConfig object:
| Field | Description | Required |
|---|---|---|
lang | Unique identifier and Shiki highlighter language (e.g. 'curl', 'javascript') | ✓ |
label | Display name shown in the UI | ✓ |
target | Target language for @scalar/snippetz code generation (e.g. 'js', 'shell') | — |
client | HTTP client for the target language (e.g. 'fetch', 'axios', 'curl') | — |
icon | Icon identifier for vitepress-plugin-group-icons | — |
highlighter | Shiki language for syntax highlighting (defaults to 'plain') | — |
Links Prefixes Configuration
Configures URL prefixes used for generated navigation links (tags and operations). Affects how links to tags and operations are built in the spec UI.
| Function | Description | Default Value |
|---|---|---|
setLinksPrefixesConfig | Sets { tags: string, operations: string }. | — |
getLinksPrefixesConfig | Gets the current links prefixes config. | — |
getTagsLinkPrefix | Gets the prefix used for tag links. | '/tags/' |
getOperationsLinkPrefix | Gets the prefix used for operation links. | '/operations/' |
useTheme({
linksPrefixes: {
tags: '/tags/',
operations: '/operations/',
},
})Operation Configuration
| Function | Description | Default Value | Allowed Values |
|---|---|---|---|
setOperationBadges | Sets the operation badges. The order is respected. | ['deprecated'] | ['deprecated', 'operationId'] |
getOperationBadges | Gets the current operation badges. | — | — |
setOperationSlots | Sets which slots are rendered (order is respected). | See Custom Slots | OperationSlot[] |
getOperationSlots | Gets the list of slots to render. | — | — |
setOperationHiddenSlots | Sets which slots are hidden (filtered out from render). | [] | OperationSlot[] |
getOperationHiddenSlots | Gets the list of hidden slots. | — | — |
setOperationCols | Sets the operation layout columns (1 or 2). | 2 | 1 | 2 |
getOperationCols | Gets the current column layout. | — | — |
setOperationDefaultBaseUrl | Sets the default base URL. | 'http://localhost' | string |
getOperationDefaultBaseUrl | Gets the default base URL. | — | — |
I18n Configuration
| Function | Description | Default Value | Allowed Values |
|---|---|---|---|
setI18nConfig | Sets the i18n configuration. | { locale: 'en', fallbackLocale: 'en', messages: locales } | { locale: 'es' | 'en' | 'ja' | 'pt-BR' | string, fallbackLocale: 'es' | 'en' | 'ja' | 'pt-BR' | string, messages: Messages, availableLocales: AvailableLocale[] } |
getI18nConfig | Gets the full i18n config. | — | — |
getLocale | Gets the active locale code. | 'en' | — |
Spec Configuration
| Function | Description | Default Value | Allowed Values |
|---|---|---|---|
setSpecConfig | Sets the spec configuration. | { groupByTags: true, collapsePaths: false, showPathsSummary: true, avoidCirculars: false, lazyRendering: false, defaultTag: 'Default', wrapExamples: true, disableDownload: false } | { groupByTags: boolean, collapsePaths: boolean, showPathsSummary: boolean, avoidCirculars: boolean, lazyRendering: boolean, defaultTag: string, wrapExamples: boolean, disableDownload: boolean } |
getSpecConfig | Gets the full spec config object. | — | — |
getWrapExamples | Gets whether examples are wrapped in a row layout. | true | true, false |
getSpecDisableDownload | Gets whether the download button in the info section is disabled. | false | true, false |
Server Configuration
| Function | Description | Default Value | Allowed Values |
|---|---|---|---|
setServerConfig | Sets the server configuration. | { getServers: null, allowCustomServer: false } | { getServers: ({ method, path, operation }) => string[], allowCustomServer: boolean } |
getServerConfig | Gets the full server config object. | — | — |
getOperationServers | Gets the servers function for an operation. | null | ({ method, path, operation }) => string[] |
getServerAllowCustomServer | Gets whether custom servers are allowed. | false | true, false |
Storage Configuration
| Function | Description | Default Value | Allowed Values |
|---|---|---|---|
setStorageConfig | Sets the storage configuration. | — | — |
getStoragePrefix | Returns the current localStorage key prefix. | '--oa' | string |
getStoragePersistAuth | Returns whether auth values are persisted to localStorage. | true | true, false |
Markdown Configuration
| Function | Description | Default Value | Allowed Values |
|---|---|---|---|
setMarkdownConfig | Sets the markdown configuration. | { operationLink: { linkPrefix: '/operations/' }, externalLinksNewTab: false, sanitize: true } | { operationLink: { linkPrefix: string, transformHref: (href: string) => string } | false, externalLinksNewTab: boolean, config: (md) => MarkdownIt, sanitize: boolean | ((html: string) => string) } |
getMarkdownConfig | Gets the markdown configuration. | — | — |
getOperationLinkConfig | Gets the operation link configuration. | { linkPrefix: '/operations/' } | { linkPrefix: string, transformHref: (href: string) => string } | false |
getExternalLinksNewTab | Gets whether external links open in new tab. | false | true, false |
Setting operationLink to false disables the operation link plugin entirely.
You can also customize the markdown renderer with the config callback:
useTheme({
markdown: {
config: md => {
// add custom markdown-it plugins
md.use(myPlugin, myParams)
return;
// or return your own instance
const myMd = (/* ... */)
return myMd
},
},
})md is an instance of markdown-it.
Sanitization
HTML in Markdown descriptions is sanitized by default. Formatting markup such as headings, lists, tables, code blocks, links, images, <br> and <details> is kept, while scripts, event handler attributes (onclick, onerror, …), embedded frames and unsafe URLs (e.g. javascript:) are removed. Sanitization runs on the final HTML, so it also applies to plugins added with config.
Use the sanitize option to change this behavior:
useTheme({
markdown: {
// Replace the built-in sanitizer with your own.
sanitize: html => mySanitizer(html),
},
})Setting sanitize: false renders the HTML from your descriptions as-is. Only disable it when the OpenAPI specs come from a fully trusted source.