On this page
Data Attributes#
All SDK options can be set as data-* attributes on the script tag for a zero-JavaScript setup. This is the simplest integration method — no JavaScript code required.
Widget Configuration#
Core attributes that control which widget loads and how it behaves.
- Attribute
data-api-key- JS Property
apiKey- Required
- Required
- Description
- Your public widget API key (pk_live_...).
- Attribute
data-mode- JS Property
—- Required
- Optional
- Description
- Deployment mode: "chatbox" or "bubble" (default).
| Attribute | JS Property | Required | Description |
|---|---|---|---|
data-api-key | apiKey | Required | Your public widget API key (pk_live_...). |
data-mode | — | Optional | Deployment mode: "chatbox" or "bubble" (default). |
Bubble Styling#
Customize the floating bubble button appearance. These only apply when using bubble mode (the default).
- Attribute
data-bubble-color- JS Property
bubbleColor- Default
"#6366f1"- Description
- Background color of the floating button (6-digit hex color, e.g. #6366f1).
- Attribute
data-bubble-size- JS Property
bubbleSize- Default
56- Description
- Diameter of the floating button in pixels (min 1px).
- Attribute
data-bubble-icon- JS Property
bubbleIcon- Default
built-in chat icon- Description
- Custom bubble icon — an inline SVG string or an image URL.
- Attribute
data-bubble-icon-size- JS Property
bubbleIconSize- Default
43% of bubbleSize- Description
- Icon size in pixels. Defaults to ~43% of the bubble diameter (e.g. 24px for a 56px bubble).
- Attribute
data-position- JS Property
position- Default
"bottom-right"- Description
- Corner to place the bubble and chat panel: "bottom-right" or "bottom-left".
- Attribute
data-offset-bottom- JS Property
offset.bottom- Default
20- Description
- Distance from the bottom edge of the viewport in pixels.
- Attribute
data-offset-right- JS Property
offset.right- Default
20- Description
- Distance from the right edge of the viewport in pixels (bottom-right position).
- Attribute
data-offset-left- JS Property
offset.left- Default
20- Description
- Distance from the left edge of the viewport in pixels (bottom-left position).
| Attribute | JS Property | Default | Description |
|---|---|---|---|
data-bubble-color | bubbleColor | "#6366f1" | Background color of the floating button (6-digit hex color, e.g. #6366f1). |
data-bubble-size | bubbleSize | 56 | Diameter of the floating button in pixels (min 1px). |
data-bubble-icon | bubbleIcon | built-in chat icon | Custom bubble icon — an inline SVG string or an image URL. |
data-bubble-icon-size | bubbleIconSize | 43% of bubbleSize | Icon size in pixels. Defaults to ~43% of the bubble diameter (e.g. 24px for a 56px bubble). |
data-position | position | "bottom-right" | Corner to place the bubble and chat panel: "bottom-right" or "bottom-left". |
data-offset-bottom | offset.bottom | 20 | Distance from the bottom edge of the viewport in pixels. |
data-offset-right | offset.right | 20 | Distance from the right edge of the viewport in pixels (bottom-right position). |
data-offset-left | offset.left | 20 | Distance from the left edge of the viewport in pixels (bottom-left position). |
Signed-in Visitors & Details#
Give the widget the visitor’s token, and pass unverified details (name, email) for greetings and hand-off. See Signed-in visitors for the full guide and User Sessions for sign-in and sign-out. There is deliberately no attribute that holds the token itself, and none that sets a visitor id: Gydr makes the visitor id.
- Attribute
data-visitor-token-endpoint- JS Equivalent
setVisitorTokenProvider()- Description
- A path on your own site that returns
{ "visitorToken": "…", "expiresIn": 3600 }or{ "visitorToken": null }for a guest. The widget calls it with the visitor’s cookies, never cached, and again before the token expires. Same origin only; a provider set in JavaScript wins when both are present. See give the widget the token.
- Attribute
data-visitor-name- JS Equivalent
setVisitorDetails({ name })- Description
- Visitor display name. Used for personalized greetings.
- Attribute
data-visitor-email- JS Equivalent
setVisitorDetails({ email })- Description
- Visitor email address.
- Attribute
data-visitor-phone- JS Equivalent
setVisitorDetails({ phone })- Description
- Visitor phone number.
- Attribute
data-visitor-company- JS Equivalent
setVisitorDetails({ company })- Description
- Visitor company or organization name.
- Attribute
data-visitor-latitude- JS Equivalent
setVisitorDetails({ location: { latitude } })- Description
- Optional. Visitor latitude in decimal degrees (-90 to 90). When paired with longitude, pre-fills the visitor's location and skips the in-chat location prompt for proximity questions.
- Attribute
data-visitor-longitude- JS Equivalent
setVisitorDetails({ location: { longitude } })- Description
- Optional. Visitor longitude in decimal degrees (-180 to 180). Must be provided together with latitude.
| Attribute | JS Equivalent | Description |
|---|---|---|
data-visitor-token-endpoint | setVisitorTokenProvider() | A path on your own site that returns { "visitorToken": "…", "expiresIn": 3600 } or { "visitorToken": null } for a guest. The widget calls it with the visitor’s cookies, never cached, and again before the token expires. Same origin only; a provider set in JavaScript wins when both are present. See give the widget the token. |
data-visitor-name | setVisitorDetails({ name }) | Visitor display name. Used for personalized greetings. |
data-visitor-email | setVisitorDetails({ email }) | Visitor email address. |
data-visitor-phone | setVisitorDetails({ phone }) | Visitor phone number. |
data-visitor-company | setVisitorDetails({ company }) | Visitor company or organization name. |
data-visitor-latitude | setVisitorDetails({ location: { latitude } }) | Optional. Visitor latitude in decimal degrees (-90 to 90). When paired with longitude, pre-fills the visitor's location and skips the in-chat location prompt for proximity questions. |
data-visitor-longitude | setVisitorDetails({ location: { longitude } }) | Optional. Visitor longitude in decimal degrees (-180 to 180). Must be provided together with latitude. |
Full Example#
A complete embed snippet using data attributes for styling, signed-in visitors, and mode configuration.
<script
src="https://cdn.infinichat.dev/widget.js"
data-api-key="pk_live_YOUR_KEY"
data-mode="bubble"
data-bubble-color="#10b981"
data-bubble-size="64"
data-bubble-icon="https://example.com/icon.svg"
data-visitor-token-endpoint="/gydr/visitor-token"
data-visitor-name="Sarah"
async
></script>Attribute → Property Mapping#
Data attributes map directly to the JavaScript API property names. The SDK reads attributes from the script tag at load time and applies them automatically.
Data-attribute auto-init and the JavaScript API are mutually exclusive. Once the script tag has initialized the widget, calling
Gydr.bubble() or Gydr.chatbox() will warn and no-op. To reconfigure programmatically, call Gydr.reset() first, then call bubble() or chatbox() with the new options — that call replaces the existing widget.