A chat widget that looks borrowed gets treated as borrowed. Visitors are good at spotting the bolt-on — the wrong blue, the font that belongs to somebody else's site — and they trust it accordingly.
The Appearance tab is where you fix that. Nothing on it changes what the assistant says; it changes where it sits, what it is made of, and what visitors see before they open it.
Open your assistant and select Appearance. Changes are held locally until you press Save (⌘S / Ctrl+S), and Preview always opens the last saved version.
1. Pick the display mode
Two presentations sit at the top of the tab as a pair of cards.
| Mode | What visitors see |
|---|---|
| Widget | A round assistant orb parked in one corner with the name under it. Tapping it opens the chat. |
| Minimal | An ambient pill with a settings gear; the page stays visible and clickable, and the chat panel docks to one side. |
Most sites want Widget. Pick Minimal when the assistant is doing something to the page — walking someone through a form, an in-app helper, a kiosk-style screen.
Minimal reveals one extra setting: Waves at the Bottom, a full-width ambient waves band along the bottom of the page. It is off by default, leaving Minimal as just the pill and its gear.
2. Put it somewhere it does not collide
| Control | Range | Notes |
|---|---|---|
| Position | Bottom Left / Bottom Right / Top Left / Top Right | Which corner it sits in. In Minimal mode it also decides which side the panel docks to. |
| Size | 50px – 120px | Orb diameter. |
| Horizontal Offset | 0px – 200px | Distance from the left or right edge. |
| Vertical Offset | 0px – 300px | Distance from the top or bottom edge. |
Bottom-right is the default and the convention, which is exactly why you should check it against your own site: cookie banners, back-to-top buttons, sticky "Add to cart" bars and toasts all congregate there. Raise the Vertical Offset until the collision stops rather than moving the orb somewhere unexpected. Offsets below 20px render as 20px — the widget keeps a minimum clearance from the edge.
3. Colours: you style the accents, not the chat
The chat surfaces — panel background and message text — follow the visitor's own light or dark theme automatically, so the assistant stays legible on any site, including sites with a light/dark toggle. Setting a chat background colour does not repaint the panel. The colours here style the accents: Accent/Ring covers borders, rings and dividers, and Primary covers the voice icon, buttons and focus rings. Each takes a swatch or a hex value.
Five preset chips — Dark, Light, Purple, Blue and Green — write a whole palette at once, including all four wave state colours. Pick the one nearest your brand, then replace Primary with your actual brand hex. The chip stays highlighted only while every colour still matches the preset, so the moment the highlight clears you have confirmation your edit landed.
4. The four state colours are functional, not decorative
Under Wave Appearance, the orb changes colour and movement to tell a visitor what the assistant is doing. Each state has its own colour field.
| State | What it tells the visitor | Movement |
|---|---|---|
| Idle | Waiting. Nothing is being recorded or processed. | A slow, calm breath. |
| Listening | The microphone is open. | A tighter, faster breath with a brighter ring. |
| Speaking | The assistant is talking. | The glow intensifies and pulses with the speech. |
| Processing | Working — transcribing, thinking, running a tool. | A slow "thinking" breath; the glow drops away. |
With voice enabled, Listening and Speaking carry the entire "is it my turn?" signal. Pick two a visitor can tell apart at a glance, and resist making all four your brand colour — four shades of the same teal is a beautiful, useless traffic light. See Choosing a Voice for Your Assistant for the rest of the voice setup.
Show waves is on by default; turn it off for a plain orb. It applies to the corner Widget presentation — Minimal has its own Waves at the Bottom switch. Wave Speed (0.2x–2.0x) and Wave Height (0.3x–2.0x) drive the animation, and a calmer site usually wants both near the low end.
5. Typography
- Font Family — System Default plus a long list of web fonts, loaded from Google Fonts on the visitor's page. The box underneath previews your pick.
- Display Font (10–20px) — size of the caption bubble beside the orb.
- Chat Font (10–20px) — size of the messages inside the chat panel.
- Bubble Width (200–600px) and Chat Width (280–500px) — max width of the caption bubble and the chat panel.
If your site already loads a brand font, choosing the same family here is what makes the widget stop looking bolted on — a bigger win than any colour change. And keep Chat Font at a comfortable reading size: the chat panel is where visitors do all their reading, so shrinking it to save space is a false economy.
6. What visitors see before they open it
The Widget Display section controls the copy around the orb: Widget Title is the name on the chip below it (leave it empty for no chip), Welcome Message is the line shown above it while idle, and two sliders set how long that message waits before appearing (0–5,000ms) and how long it stays (0–60,000ms, where 0 reads Never).
The common mix-up: Welcome Message is the caption beside the orb, not the assistant's first chat message. The opening chat message comes from the greetings on the General tab. If your greeting looks wrong, check which of the two you edited.
Once it times out it fades and stays hidden for the rest of that browser session, so a visitor moving between pages is not nagged on every one. A short delay reads as an offer; instant reads as a pop-up.
7. Logo and branding
Logo (optional) takes the address of an image you already host. Paste an https:// URL — there is no upload, and a data: URL is rejected on save. Once a logo is set, a preview card appears with a Remove button and one extra switch: Always show logo keeps the logo visible, faded, behind the waveform while the assistant is active. With it off, the logo shows only while the assistant is idle.
Under Powered By, Hide Branding removes the small by hiroi badge under the orb. It is a paid feature — on a free account the switch carries a PAID badge and refuses to turn on. See the pricing page.
8. Custom CSS, only if you need it
Custom CSS Rules (optional) takes raw CSS that the widget injects into the page when it loads. It is an escape hatch with real constraints:
- Widget class names all start with
va-—.va-container,.va-orb,.va-chat-backdrop. Those are the handles. - The rules are injected into the host page's
<head>and are not scoped to the widget, so a loose selector likebutton { … }will restyle your own site. Anchor every selector to ava-class. - The field is filtered. Attribute selectors must be unquoted, at-rules with nested blocks (including
@media) are dropped, andurl(anywhere discards the whole sheet — load web fonts on your page and reference the family by name instead.
Everything above survives widget updates. Custom CSS is written against the current markup and can break when the widget changes, so reach for the built-in controls first.
A five-minute brand pass
- Set Display Mode and Position, then check both on a phone.
- Apply the nearest preset, then replace Primary with your brand hex.
- Make Listening and Speaking visibly different from each other.
- Set Font Family to your site's font.
- Write the Widget Title and Welcome Message in your own voice.
- Add your logo URL, and turn on Hide Branding if your account allows it.
- Save, then load your real site — not the preview. Your own CSS, your header and your cookie banner all get a vote.
If you have not embedded the widget yet, Your First 15 Minutes With Hiroi covers that end; when you are close to launch, run the Go-Live Checklist.
Everything here is live-editable at hiroi.ai — a save takes effect on the next page load, with nothing to redeploy.