Repository Public
1# Theming and customization in ChatKit23> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.45After following the [ChatKit quickstart](https://developers.openai.com/api/docs/guides/chatkit), learn how to change themes and add customization to your chat embed. Match your app’s aesthetic with light and dark themes, setting an accent color, controlling the density, and rounded corners.67## Overview89At a high level, customize the theme by passing in an options object. If you followed the [ChatKit quickstart](https://developers.openai.com/api/docs/guides/chatkit) to embed ChatKit in your frontend, use the React syntax below.1011- **React**: Pass options to `useChatKit({...})`12- **Advanced integrations**: Set options with `chatkit.setOptions({...})`1314In both integration types, the shape of the options object is the same.1516## Explore customization options1718Visit [ChatKit Studio](https://chatkit.studio) to see working implementations of ChatKit and interactive builders. If you like building by trying things rather than reading, these resources are a good starting point.1920#### Explore ChatKit UI2122[chatkit.world23242526 Play with an interactive demo of ChatKit.](https://chatkit.world)2728[Widget builder29303132 Browse available widgets.](https://widgets.chatkit.studio)3334[ChatKit playground35363738 Play with an interactive demo to learn by doing.](https://chatkit.studio/playground)3940#### See working examples4142[Samples on GitHub43444546 See working examples of ChatKit and get inspired.](https://github.com/openai/openai-chatkit-advanced-samples)4748[Starter app repo49505152 Clone a repo to start with a fully working template.](https://github.com/openai/openai-chatkit-starter-app)5354## Change the theme5556Match the look and feel of your product by specifying colors, typography, and more. Below, we set to dark mode, change colors, round the corners, adjust the information density, and set the font.5758For all theming options, see the [API reference](https://openai.github.io/chatkit-js/api/openai/chatkit/type-aliases/themeoption/).5960```javascript61const options = {62 theme: {63 colorScheme: "dark",64 color: {65 accent: {66 primary: "#2D8CFF",67 level: 2,68 },69 },70 radius: "round",71 density: "compact",72 typography: { fontFamily: "'Inter', sans-serif" },73 },74};75```767778## Customize the start screen text7980Let users know what to ask or guide their first input by changing the composer’s placeholder text.8182```javascript83const options = {84 composer: {85 placeholder: "Ask anything about your data…",86 },87 startScreen: {88 greeting: "Welcome to FeedbackBot!",89 },90};91```929394## Show starter prompts for new threads9596Guide users on what to ask or do by suggesting prompt ideas when starting a conversation.9798```javascript99const options = {100 startScreen: {101 greeting: "What can I help you build today?",102 prompts: [103 {104 name: "Check on the status of a ticket",105 prompt: "Can you help me check on the status of a ticket?",106 icon: "search",107 },108 {109 name: "Create Ticket",110 prompt: "Can you help me create a new support ticket?",111 icon: "write",112 },113 ],114 },115};116```117118119## Add custom buttons to the header120121Custom header buttons help you add navigation, context, or actions relevant to your integration.122123```javascript124const options = {125 header: {126 customButtonLeft: {127 icon: "settings-cog",128 onClick: () => openProfileSettings(),129 },130 customButtonRight: {131 icon: "home",132 onClick: () => openHomePage(),133 },134 },135};136```137138139## Enable file attachments140141Attachments are disabled by default. To enable them, add attachments configuration.142Unless you are doing a custom backend, you must use the `hosted` upload strategy.143See the Python SDK docs for more information on other upload strategies work with a custom backend.144145You can also control the number, size, and types of files that users can attach to messages.146147```javascript148const options = {149 composer: {150 attachments: {151 uploadStrategy: { type: "hosted" },152 maxSize: 20 * 1024 * 1024, // 20 MB per file153 maxCount: 3,154 accept: { "application/pdf": [".pdf"], "image/*": [".png", ".jpg"] },155 },156 },157};158```159160161## Enable @mentions in the composer with entity tags162163Let users tag custom “entities” with @-mentions. This enables richer conversation context and interactivity.164165- Use `onTagSearch` to return a list of entities based on the input query.166- Use `onClick` to handle the click event of an entity.167168```javascript169const options = {170 entities: {171 async onTagSearch(query) {172 void query;173 return [174 {175 id: "user_123",176 title: "Jane Doe",177 group: "People",178 interactive: true,179 },180 {181 id: "document_123",182 title: "Quarterly Plan",183 group: "Documents",184 interactive: true,185 },186 ];187 },188 onClick: (entity) => {189 navigateToEntity(entity.id);190 },191 },192};193```194195196## Customize how entity tags appear197198You can customize the appearance of entity tags on mouseover using widgets. Show rich previews such as a business card, document summary, or image when the user hovers over an entity tag.199200[Widget builder201202203204 Browse available widgets.](https://widgets.chatkit.studio)205206```javascript207const options = {208 entities: {209 async onTagSearch() {210 return [];211 },212 onRequestPreview: async (entity) => ({213 preview: {214 type: "Card",215 children: [216 { type: "Text", value: `Profile: ${entity.title}` },217 { type: "Text", value: "Role: Developer" },218 ],219 },220 }),221 },222};223```224225226## Add custom tools to the composer227228Enhance productivity by letting users trigger app-specific actions from the composer bar. The selected tool229will be sent to the model as a tool preference.230231```javascript232const options = {233 composer: {234 tools: [235 {236 id: "add-note",237 label: "Add Note",238 icon: "write",239 pinned: true,240 },241 ],242 },243};244```245246247## Toggle UI regions and features248249Disable major UI regions and features if you need more customization over the options available in the header and want to implement your own instead. Disabling history can be useful when the concept of threads and history doesn't make sense for your use case—e.g., in a support chatbot.250251```javascript252const options = {253 history: { enabled: false },254 header: { enabled: false },255};256```257258259## Override the locale260261Override the default locale if you have an app-wide language setting. By default, the locale is set to the browser's locale.262263```javascript264const options = {265 locale: "de-DE",266};267```