ChatKit Frontend Bootstrap Skill

ChatKit Frontend Bootstrap

Embed and initialize OpenAI's ChatKit widget in Rails views.

When to Use

Embedding ChatKit as a custom <openai-chatkit> element
Configuring ChatKit options (API URL, attachments, theme)
Theme synchronization with app-wide dark/light mode
Building both embedded and standalone ChatKit pages

Quick Start

1. Add Bootstrap Partial to Head

<% content_for :head do %>
  <%= render "shared/chatkit_bootstrap" %>
<% end %>

2. Create Container with Data Attributes

<div class="chatkit-shell__frame"
     data-chatkit-api-url-value="<%= chatkit_url %>?agent_id=<%= @agent.id %>"
     data-chatkit-domain-key-value="<%= @chatkit_settings[:domain_key] %>"
     data-chatkit-upload-url-value="<%= chatkit_upload_url(agent_id: @agent.id) %>"
     data-chatkit-upload-max-size-value="<%= ChatkitConfig.upload_max_bytes %>"
     data-chatkit-upload-accept-value="<%= ChatkitConfig.allowed_mime_types.join(',') %>">
</div>

3. Add Required CSS

.chatkit-shell__frame {
  min-height: 520px;
  height: 100%;
  flex: 1 1 auto;
  display: flex;
}

.chatkit-shell__frame > openai-chatkit {
  flex: 1 1 auto;
  width: 100%;
  height: 100%;
}

Key Patterns

Data Attribute Configuration

The bootstrap JavaScript reads options from container data attributes:

| Attribute | Purpose | |-----------|---------| | data-chatkit-api-url-value | Backend API endpoint | | data-chatkit-domain-key-value | Domain verification key | | data-chatkit-client-secret-path-value | Endpoint for hosted mode secrets | | data-chatkit-upload-url-value | File upload endpoint | | data-chatkit-upload-max-size-value | Max upload size in bytes | | data-chatkit-upload-accept-value | Allowed MIME types (comma-separated) | | data-chatkit-initial-thread-value | Thread ID to load on init | | data-chatkit-header-title-value | Header title text |

Theme Sync

ChatKit automatically syncs with document.documentElement.dataset.theme:

const observer = new MutationObserver((mutations) => {
  if (mutations.some((m) => m.attributeName === "data-theme")) {
    syncTheme()
  }
})
observer.observe(document.documentElement, { attributes: true, attributeFilter: ["data-theme"] })

Turbo Integration

Works with Turbo by listening to both events:

document.addEventListener("turbo:load", applyOptions)
document.addEventListener("DOMContentLoaded", applyOptions)

Reference Files

For detailed implementation patterns, see:

embedding.md - View integration patterns
initialization.md - JavaScript setup and options
theming.md - Theme synchronization
configuration.md - ChatkitConfig and environment
styling.md - CSS patterns

File Locations

| Component | Path | |-----------|------| | Bootstrap partial | app/views/shared/_chatkit_bootstrap.html.erb | | Agent ChatKit view | app/views/agents/chatkit.html.erb | | Standalone view | app/views/agents/chatkit_standalone.html.erb | | CSS | app/assets/stylesheets/components/chatkit.css | | Configuration | app/models/chatkit_config.rb |

Two Modes

Self-Hosted Mode (Default)

ChatKit connects to your Rails backend. No external dependencies.

# Environment (optional - uses defaults)
CHATKIT_API_URL="/chatkit"

Hosted Mode (OpenAI Infrastructure)

ChatKit connects to OpenAI servers, requires client secret.

# Environment (required)
CHATKIT_CLIENT_SECRET="sk-..."
CHATKIT_PK="your-domain-key"

Example Controller Setup

def chatkit
  @chatkit_settings = {
    api_url: "#{chatkit_url}?agent_id=#{@agent.id}",
    domain_key: ChatkitConfig.domain_key,
    upload_url: chatkit_upload_url(agent_id: @agent.id),
    upload_max_bytes: ChatkitConfig.upload_max_bytes,
    allowed_mime_types: ChatkitConfig.allowed_mime_types,
    header_title: @agent.name,
    initial_thread: params[:thread_id]
  }

  if ChatkitConfig.hosted?
    @chatkit_settings[:client_secret_path] = chatkit_client_secret_path
  end
end

Agent Skills: ChatKit Frontend Bootstrap

Install this agent skill to your local

Skill Files