Customize widget appearance

The Appearance tab covers the basics. This page is for the deeper knobs — embed-level overrides, dark-mode handling, multi-language, and runtime swaps.

In this guide:

• Embed-time options vs. dashboard options
• Dark mode
• Custom fonts
• Welcome messages and floating prompts
• Mobile vs. desktop sizing

Embed-time options vs. dashboard options

A dashboard change updates everywhere instantly; an embed override only affects the pages you re-deploy.

Dark mode

Two ways to handle dark mode:

1. Static: pass theme: 'dark' in the embed init. Always dark, regardless of host.
2. Match host: the widget detects prefers-color-scheme and follows. Set theme: 'auto' (or omit; auto is default).

For sites with their own theme toggle, use the developer JS API to call setTheme('dark' | 'light') whenever the user toggles.

Custom fonts

The bundled fonts (system, Inter, Roboto, Lato) cover most needs. To use a host-page custom font:

1. Make sure the font is loaded on the host page (via @font-face or Google Fonts <link>).
2. In the embed init, pass fontFamily: 'Your Font Name, sans-serif'.

Because the widget renders inside a shadow DOM, the font must be available outside the shadow root and the widget will inherit it.

Welcome messages

Two layers:

• Welcome message — the teaser bubble shown before users open the chat.
• Greeting (opening) message — sent automatically when users open the chat for the first time in a session.

Both configurable from the Appearance tab. For per-page context (e.g., “I see you’re on the pricing page — questions about plans?”), use initialMessages.pageContext from the Developer embed JS API (New).

Floating prompts

Floating prompts are clickable suggestion bubbles that appear beside the chat icon — quick links into common conversations.

Configure them in:

• Dashboard → Appearance → Floating prompts for org-wide defaults.
• Per-page via initialMessages.floating: ['What is your cheapest plan?', 'Do you offer refunds?'] in the embed init (New).

Mobile vs. desktop sizing

The widget auto-adjusts:

• Desktop: max width 500px, configurable height.
• Mobile (≤ 768px): full-screen overlay (95vw / 95vh) for readability.

To override:

window.HilalChat.init({
  // ...
  size: {
    desktop: { width: 420, height: 640 },
    mobile: { width: '100vw', height: '100vh' }
  }
});

Z-index conflicts

The widget renders at a high z-index (default 999999). If your site has overlays at higher z-indexes, override:

window.HilalChat.init({ zIndex: 9999999 });

Animations

The widget uses smooth open/close animations by default. To disable for accessibility (prefers-reduced-motion), the widget already respects the user’s OS setting — no config needed. To force-disable globally:

window.HilalChat.init({ animations: false });

Tips

• Match border-radius to your site. A pill-shaped chat bubble next to a square site header looks pasted-on. Set borderRadius: 12 (or whatever).
• Check on mobile every time. Desktop preview is misleading; the widget transforms on mobile.
• Don’t compete with site UI. A bottom-right widget over a chat-app’s compose box is an accidental footgun.

What’s next