Attributes

This page lists every script-tag attribute the CDN widget reads and the matching npm option where one exists.

Only data-project-id is required. Invalid enum, language, and hex color values are ignored with a console warning.

Identity

Script attribute	npm option	Type	Default
`data-project-id`	`projectId`	UUID	Required

Behavior

Script attribute	npm option	Type	Default
`data-theme`	`theme`	`auto`, `light`, `dark`	`auto`
`data-language`	`language`	`en`, `tr`, `de`, `es`, `fr`, `it`, `pt`, `nl`, `ja`, `ko`, `zh`, `ru`, `cs`	Browser-detected, then `en`
`data-layout`	`layout`	`modal`, `overlay`, `push`	`modal`
`data-open-selector`	`openSelector`	CSS selector	None
`data-mode`	`mode`	`chat`, `deflector`	`chat`
`data-form-selector`	`formSelector`	CSS selector	Required for deflector mode
`data-subject-selector`	`subjectSelector`	CSS selector	None
`data-body-selector`	`bodySelector`	CSS selector	None

data-open-selector binds clicks on matching elements. It also watches the DOM, so triggers rendered later by React, Vue, Docusaurus, VitePress, or another client router still work.

data-mode="deflector" turns the widget into a support form deflector. It requires Business or above and data-form-selector. See Support form deflector.

Launcher

Script attribute	npm option	Type	Default
`data-launcher-align`	`launcherAlign`	`bottom-right`, `bottom-left`	`bottom-right`
`data-launcher-hidden`	`launcherHidden`	`true`, `false`	`false`
`data-launcher-text`	`launcherText`	Text	`Ask Docs`
`data-launcher-subtitle`	`launcherSubtitle`	Text	Empty
`data-launcher-icon`	`launcherIcon`	Built-in icon name	`book-open`
`data-launcher-style`	`launcherStyle`	`pill`, `card`	`pill`
`data-launcher-icon-position`	`launcherIconPosition`	`left`, `right`	`right`
`data-launcher-show-icon`	`launcherShowIcon`	`true`, `false`	`true`

The default launcher is the compact pill style with Ask Docs and the book-open icon.

The legacy card style displays two lines. If you switch to card without overriding copy, the visual fallback is Need help? and Ask AI; explicit data-launcher-text and data-launcher-subtitle always win.

Copy

Script attribute	npm option	Type	Default
`data-greeting`	`greeting`	Text	Empty
`data-suggested-questions`	`suggestedQuestions`	Comma-separated text, optional `	icon-name`. Escape` ,`,`

Example:


data-suggested-questions="Get started|rocket,API reference|code,Pricing|card"

Questions containing commas or | in the script tag must escape them (\,, \|). The dashboard snippet does this automatically. Or use the npm object form:


suggestedQuestions: [
  { text: 'Install, configure, and verify the widget', icon: 'rocket' },
  'How does pricing work?',
]

Colors

Script attribute	npm option	Type	Default
`data-primary-color`	`primaryColor`	`#RRGGBB`	Sets light and dark together
`data-primary-color-light`	`primaryColorLight`	`#RRGGBB`	`#171717`
`data-primary-color-dark`	`primaryColorDark`	`#RRGGBB`	`#d4d4d4`

Primary colors affect the launcher, submit button, and focus states. For per-slot styling, use Component styles.

Script attribute	npm option	Type	Default
`data-consent-required`	`consent.required`	`true`, `false`	`false`
`data-consent-title`	`consent.title`	Text	Language default
`data-consent-disclaimer`	`consent.disclaimer`	Text	Language default
`data-consent-accept-text`	`consent.acceptText`	Text	Language default
`data-consent-reject-text`	`consent.rejectText`	Text	Language default

When consent is required, Knoku.ask(question) opens the consent screen first and submits the held question after the visitor accepts.

Component styles

Per-slot style overrides use this pattern:


data-{slot}-{property}
data-{slot}-{state}-{property}
data-{slot}-{property}-dark
data-{slot}-{state}-{property}-dark

See Component styles for all slots and allowed CSS properties.

npm-only options

These options exist on initKnokuWidget() but are not parsed from the CDN script tag:

npm option	Purpose
`apiUrl`	Override the API origin, usually for local development
`hostId`	Override the generated widget host element ID
`primaryDomain`	Override the source-link base used by citations
`preview` / `previewSurface`	Dashboard preview mode

Example


import { initKnokuWidget } from '@knoku/widget'
 
await initKnokuWidget({
  projectId: 'YOUR_PROJECT_ID',
  theme: 'auto',
  language: 'en',
  layout: 'modal',
  greeting: 'How can I help?',
  launcherText: 'Ask Docs',
  launcherStyle: 'pill',
  launcherIcon: 'book-open',
  openSelector: '#ask-ai',
  suggestedQuestions: [
    { text: 'Get started', icon: 'rocket' },
    { text: 'API reference', icon: 'code' },
  ],
  consent: {
    required: true,
    title: 'Use the AI assistant?',
  },
  componentStyles: {
    'panel-header': { 'background-color': '#ffffff' },
    'panel-header:dark': { 'background-color': '#020617' },
  },
})