> For the complete documentation index, see [llms.txt](https://shoppad.gitbook.io/yedric/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://shoppad.gitbook.io/yedric/getting-started/widget.md).
# Widget
The Widget tab is where you control how Yedric looks and behaves inside your app. You can customize the appearance, set a greeting, and preview your changes in real time before going live.
The Widget page has four tabs: **Configure** for colors, layout, and behavior, **Build character** for generating a mascot with AI (see [Build a Character](/yedric/going-further/build-character.md)), **Preview** for trying the widget against a real page, and **Install** for the embed code your developer adds to your app.
{% hint style="info" %}
**Ready to install?** See [Embedding the Widget](/yedric/developers/embedding-widget.md) in the Developers section for the full setup walkthrough and complete attribute reference.
{% endhint %}
Preview will let you view how your assistant appears on your app or website.
***
## Configure
The Configure tab controls the basic behavior of the widget.
**Side** sets whether the widget appears on the left or right side of the screen. The default is Right. Visitors can also drag the launcher to another corner if it covers something they need, and the widget remembers their choice for your assistant on their next visit. Your developer can turn this off for a page with the `fab-draggable` attribute described in [Embedding the Widget](/yedric/developers/embedding-widget.md).
**Default state** controls whether the widget loads open or closed. Closed means only the launcher button is visible until a user clicks it. On phones the widget starts closed either way, since an open panel fills a small screen. Tablets and desktops open as configured.
**Show Page prompts when beacon is closed** appears when Default state is Closed. When checked, the current page's [Page Prompts](/yedric/getting-started/page-prompts.md) show as clickable bubbles beside the closed launcher, so visitors can see what the assistant can do before they open it. Clicking a bubble opens the chat and sends that prompt. Visitors can dismiss the bubbles, and they return after an hour. Because the bubbles occupy the same spot, the beacon tooltip is not shown while this is on.
**Prompt suggestion** appears when that box is checked. It is an optional message of your own, shown above the page prompts with your assistant's avatar. Line breaks become separate lines in the bubble. The cluster shows at most four bubbles in total, so a page with many prompts shows only the first few. Your developer can override this prompt on a specific page with the `prompt-suggestion` attribute.
**Re-open when page changes** keeps the chat with the visitor as they move around your site. If they follow a link with the chat open, it opens again on the next page with the same conversation. Off by default. Closing the panel before leaving a page means it stays closed on the next one.
**Hide launcher** removes the floating launcher button entirely. This is useful if you want to open Yedric from your own button or trigger rather than the default floating button. Your developer can do this using the [JavaScript API](/yedric/developers/javascript-api.md).
***
## Display
The Display section in Configure controls how the widget looks.
**Theme** sets the overall color scheme. Light is the default. You can switch to Dark or customize individual colors further using the color options below.
**Panel width** controls how wide the widget panel is when open. The default is 400px. Users can also drag the edge of the open panel to resize it manually, up to 92% of their viewport width.
**Border style** adjusts the edge style of the panel. Options are Line, Shadow, and Rounded.
**Font family** sets the typeface used in the widget. Choose from a list of common fonts to match your product's design.
**Greeting** is the optional message shown above the suggestion prompts when a user first opens the widget. Leave it blank for no greeting.
**Greeting description** is a secondary line shown beneath the greeting, if you want to add a bit more context.
***
## Colors
Beyond the theme preset, you can fine-tune colors for specific parts of the widget using the color picker. Customizable areas include the title bar, message bubbles, input field, buttons, and more. Leave any field blank to use the theme default.
A few colors worth knowing about:
* **Suggestion text** and **Suggestion button background (hover)** color the starter suggestion buttons alongside their background and border, so a dark button can still have readable text and its own hover state.
* **User message text** and **Assistant message text** set the text color inside each message bubble, to pair with the bubble backgrounds.
* **Assistant avatar & beacon background** paints the tile behind the assistant's avatar in the chat and behind the launcher icon, so the character sits on the same color in both places.
For a full list of the available color variables and how to set them via the JavaScript API, see [Embedding the Widget](/yedric/developers/embedding-widget.md) and the [JavaScript API](/yedric/developers/javascript-api.md) in the Developers section.
***
## Mascot
You can give the widget a character that reacts as the conversation goes along. There are two ways to get one:
* Generate a complete set with AI on the **Build character** tab, from a description or your own logo. See [Build a Character](/yedric/going-further/build-character.md).
* Supply your own clips and icons by hand, using the fields in this section.
If you have short video clips of a mascot or character, you can configure the widget to play them at key moments. Four clips are supported:
* **Waving**: Played when the panel first opens
* **Thinking**: Played while the assistant is generating a response
* **Thumbs up**: Played when the user upvotes a response
* **Presenting**: Played when the assistant delivers a key piece of content
You can also set a static placeholder image that is shown when no clip is playing. Each clip field has an **Upload** button that accepts an MP4 or WebM file up to 10 MB, and the placeholder field accepts an image the same way. You can paste a URL instead if you host the files yourself; hosted URLs must be publicly accessible (not behind a login or CDN restriction). For recommended dimensions, see [Embedding the Widget](/yedric/developers/embedding-widget.md) in the Developers section. Leave this section blank to use the default appearance with no mascot.
***
## Chat features
**Voting**: When enabled, users see a thumbs up and thumbs down button on each assistant response. Votes are recorded and visible in the Conversations tab. On by default.
**File uploads**: When enabled, users can attach files to their messages using a paperclip button in the input field. On by default. Turn this off if file attachments are not relevant to your use case.
**Show tool activity**: When enabled, users see the step-by-step "I'm running..." status lines as the assistant works through its tools. Each step appears in the reply at the point where the assistant ran it, so the step currently running sits below the text written so far, where the reader is already looking. On by default. Turn it off to hide tool activity from users, and the widget shows typing dots instead while a tool runs.
**Live chat**: When enabled, the widget shows a button visitors can click to reach your team. What the button does depends on the **provider** you pick on the assistant's **Settings** tab. **Built-in** opens Yedric's own chat panel and connects the visitor to a teammate, which is [live chat](/yedric/going-further/live-chat.md). **External** fires a `human_support` event on your page instead, which your own chat provider, support form, or phone flow handles once your developer wires it up. See the [JavaScript API](/yedric/developers/javascript-api.md) for that event. Business hours are configured on the Settings tab either way.
**Body margin**: When enabled, opening the widget panel shifts the rest of the page content to make room, rather than overlapping it. On by default. If this causes layout issues in your app, you can turn it off.
On screens narrower than 640px, the panel automatically opens full-width regardless of the configured panel width setting.
***
## Preview URL
Enter a URL in the Preview URL field to simulate how the widget behaves on a specific page of your app. This is useful for testing Page Prompts, since suggestions and instructions change based on the current page URL. Leave it blank to preview using the current dashboard URL.
***
## Seeing your changes
To ensure the fastest possible pageload, the widget script is cached. This cache refreshes about every 2 minutes, so it can take up to that long for a saved change (a new color, greeting, or widget position, for example) to appear on your website.
You do not need to recopy the embed snippet after changing settings. The same snippet always loads your latest saved configuration once the cache refreshes.
To see a change right away without waiting, add the `yedric_fresh` query parameter to your page URL and reload the page:
```
https://your-website.com/?yedric_fresh=1
```
This tells the widget to skip the cache and fetch your latest saved settings immediately. Using a changing value such as a timestamp (for example `?yedric_fresh=1699999999`) guarantees a fresh fetch every time. The parameter only affects that page load in your own browser, so it is safe to use while testing and has no effect on your other visitors.
{% hint style="info" %}
The `yedric_fresh` parameter is meant for quick checks after saving. You do not need to add it to your embed snippet. Left to itself, the widget always catches up to your latest settings within about 2 minutes.
{% endhint %}
***
## Embed code and API key
Once your settings are ready, share the embed code and API key with your developer. The embed code is a single `
