Elaras/

Block Rendering

Blocks are structured UI components that an Elaras agent returns alongside a text message — carousels, booking pickers, forms, rating widgets, and more. Elaras ships ready-made renderers so you don't write any block UI code yourself.

Setup

Add two tags to your page — no build step needed:

<link rel="stylesheet" href="https://ask-api.elaras.ai/sdk/blocks.css">
<script src="https://ask-api.elaras.ai/sdk/blocks.js"></script>

The script exposes window.ElarasBlocks with renderBlock and renderBlocks.

Rendering blocks

Blocks arrive on the done event alongside the text response:

const { renderBlocks } = window.ElarasBlocks

for await (const event of client.stream(sessionId, message)) {
  if (event.type === 'done' && event.blocks?.length) {
    renderBlocks(messagesEl, event.blocks, (text) => client.stream(sessionId, text))
    messagesEl.scrollTop = messagesEl.scrollHeight
  }
}

renderBlocks(container, blocks, onSend)

ArgumentTypeDescription
containerHTMLElementElement to append blocks into
blocksBlock[]Block array from the chat event
onSend(text: string) => voidCalled when the user interacts with a block (button click, form submit, slot selection, etc.)

renderBlock(container, block, onSend)

Same signature but renders a single block. Unknown block.type values are silently ignored.

Image loading and scroll

Card images load asynchronously. When one finishes loading, a elaras:imageload CustomEvent bubbles up through the DOM. Listen on your messages container and re-scroll:

messagesEl.addEventListener('elaras:imageload', () => {
  messagesEl.scrollTop = messagesEl.scrollHeight
})

Theming

All styles use CSS custom properties. Override them on your container element to match your brand:

.my-chat {
  --ec-primary:      #ff6600;
  --ec-bg:           #ffffff;
  --ec-surface:      #f5f5f5;
  --ec-text:         #111111;
  --ec-text-muted:   #777777;
  --ec-border:       #e0e0e0;
  --ec-input-bg:     #fafafa;
  --ec-input-border: #cccccc;
}

Block types

elaras.card

A single card with optional image, metadata, and CTA.

{
  "type": "elaras.card",
  "spec": {
    "title": "2-bed flat, Shoreditch",
    "subtitle": "£1,200 pcm",
    "description": "Modern apartment with private balcony.",
    "image_url": "https://example.com/photo.jpg",
    "badge": "Available now",
    "metadata": [
      { "label": "beds", "value": "2" },
      { "label": "baths", "value": "1" }
    ],
    "cta": { "label": "View property", "url": "https://example.com/listing/123" }
  }
}

cta.sends sends a preset message into the chat instead of opening a URL.


elaras.carousel

A horizontally scrollable row of cards.

{
  "type": "elaras.carousel",
  "spec": {
    "cards": [ ...card specs... ]
  }
}

elaras.button_group

A set of action buttons.

{
  "type": "elaras.button_group",
  "spec": {
    "label": "What would you like to do?",
    "layout": "row",
    "buttons": [
      { "label": "Book a viewing", "sends": "I'd like to book a viewing", "style": "primary" },
      { "label": "Ask a question", "sends": "I have a question", "style": "outline" }
    ]
  }
}

layout is "row" (default) or "column".


elaras.form

An inline form. On submit, field values are interpolated into sends_template and sent as a chat message.

{
  "type": "elaras.form",
  "spec": {
    "title": "Request a callback",
    "submit_label": "Send request",
    "sends_template": "Callback request — Name: {name}, Phone: {phone}",
    "fields": [
      { "name": "name",  "label": "Full name",     "type": "text",  "required": true },
      { "name": "phone", "label": "Phone number",  "type": "tel",   "required": true },
      { "name": "time",  "label": "Best time",     "type": "select", "options": ["Morning", "Afternoon", "Evening"] }
    ]
  }
}

Field type can be "text", "email", "tel", "select", or "textarea".


elaras.banner

An info, success, or warning callout.

{
  "type": "elaras.banner",
  "spec": {
    "title": "Offer deadline: 5pm today",
    "body": "The vendor is reviewing all offers this evening.",
    "variant": "warning",
    "cta": { "label": "Make an offer", "sends": "I'd like to make an offer" }
  }
}

variant is "info" (default), "success", or "warning".


elaras.rating

A star rating widget. Replaces itself with a confirmation on selection.

{
  "type": "elaras.rating",
  "spec": {
    "prompt": "How helpful was this?",
    "scale": 5,
    "labels": { "low": "Not helpful", "high": "Very helpful" },
    "sends_template": "{value} out of {scale} stars"
  }
}

elaras.stat

A single highlighted metric.

{
  "type": "elaras.stat",
  "spec": {
    "value": "£1,200,000",
    "label": "Guide Price",
    "sublabel": "Freehold",
    "trend": "up",
    "trend_value": "+8% YoY"
  }
}

trend is "up", "down", or "neutral".


elaras.slots

A time-slot booking picker. Replaces itself with a confirmation on selection.

{
  "type": "elaras.slots",
  "spec": {
    "title": "Choose a viewing time",
    "date_label": "Thursday 19 September",
    "sends_template": "Book viewing: {time} (ref: {id})",
    "slots": [
      { "id": "v1", "time": "10:00 AM", "label": "30 min", "available": true },
      { "id": "v2", "time": "11:00 AM", "label": "30 min", "available": false },
      { "id": "v3", "time": "2:00 PM",  "label": "30 min", "available": true }
    ]
  }
}

elaras.choices

A single or multi-select question. Locks itself after submission.

{
  "type": "elaras.choices",
  "spec": {
    "question": "What type of property are you looking for?",
    "type": "multi",
    "options": ["Flat", "House", "New build", "Period property"],
    "allow_other": true,
    "other_placeholder": "Something else…"
  }
}

type is "single" (default) or "multi".


Emitting blocks from a skill

Return a _blocks key from any skill tool result:

{
  "result": "Here are the closest matches to your search.",
  "_blocks": [
    {
      "type": "elaras.carousel",
      "spec": {
        "cards": [...]
      }
    }
  ]
}

The widget and SDK both handle _blocks automatically.


Private blocks

Elaras strips _blocks from the tool result before it is passed to the AI. The language model only ever sees the result text — the data inside spec is never included in the AI's context.

What "private" means here: block spec data transits Elaras's servers (the skill response comes back to our backend, which extracts the blocks and forwards them to the widget). It is not sent to the language model. If your compliance requirement is that sensitive data must never leave your infrastructure at all, use the token pattern below instead.

{
  "result": "Here are the last three transactions on your account.",
  "_blocks": [
    {
      "type": "elaras.card",
      "spec": {
        "title": "Recent transactions",
        "metadata": [
          { "label": "14 Oct", "value": "—£42.00  Tesco" },
          { "label": "13 Oct", "value": "—£9.99   Spotify" },
          { "label": "12 Oct", "value": "+£1,200  Salary" }
        ]
      }
    }
  ]
}

The LLM sees: "Here are the last three transactions on your account." — nothing else.

Keeping data off Elaras's servers entirely

If the data must never leave your infrastructure, return a short-lived reference token in spec instead of the raw values, then fetch the real data inside a custom block renderer:

{
  "result": "Here are your recent transactions.",
  "_blocks": [
    {
      "type": "myapp.transactions",
      "spec": { "token": "eyJhbGciOi..." }
    }
  ]
}
window.ElarasChat.registerBlockRenderer('myapp.transactions', async (spec, container) => {
  const res  = await fetch(`/api/transactions?token=${spec.token}`);
  const data = await res.json();
  // render data into container
});

The widget runs as a script tag on your page — renderers execute in your page's context, so fetches go to your own domain with no CORS issues. If your renderer fetches from a different subdomain or origin you will need the appropriate CORS headers on that endpoint.


Custom block types

You're not limited to elaras.* types. Register a custom renderer on the host page and emit any namespaced block type from your skills. Register BEFORE the widget script loads so the renderer is wired up when the first block arrives:

<script>
  window.ElarasChat = window.ElarasChat || {};
  window.ElarasChat._pending = window.ElarasChat._pending || [];
  window.ElarasChat.registerBlockRenderer = window.ElarasChat.registerBlockRenderer
    || function (type, fn) { window.ElarasChat._pending.push([type, fn]); };

  window.ElarasChat.registerBlockRenderer('myapp.product_grid', (spec, container) => {
    container.innerHTML = spec.items.map(item =>
      `<div class="product-card">
         <img src="${item.image}" />
         <p>${item.name} — ${item.price}</p>
       </div>`
    ).join('');
  });
</script>
<script src="https://ask-api.elaras.ai/widget.js" data-chatbot-key="cbt_..." async></script>

Then return the custom type from any skill:

{
  "_blocks": [
    {
      "type": "myapp.product_grid",
      "spec": {
        "items": [
          { "name": "Widget Pro", "price": "£49", "image": "/img/widget.jpg" }
        ]
      }
    }
  ]
}

Naming: use your own lowercase dot-separated namespace (yourapp.block_name). Do not use the elaras.* prefix — it is reserved for built-in types and may clash with future additions. Register a renderer for every custom type you emit — unknown types are silently ignored by the widget.

Async renderers

Return a Promise and the widget marks your container with data-loading until it resolves. Useful when the renderer itself needs to fetch data:

window.ElarasChat.registerBlockRenderer('myapp.live_price', async (spec, container) => {
  const res = await fetch(`/api/price?ref=${spec.ref_token}`);
  const { price, currency } = await res.json();
  const el = document.createElement('p');
  el.textContent = `${currency}${price}`;
  container.appendChild(el);
});

If the promise rejects, the container shows "Failed to load." — override by catching inside your renderer.

Styling

Your renderer's container is <div class="ec-block-custom">, placed inside the widget's Shadow DOM. That means host-page CSS does not reach it by default — a stylesheet on your page like .ec-block-custom .product-card { ... } won't apply.

Three options:

  • Inline styles on the elements you create (el.style.fontSize = '1.5rem') — simplest
  • Inject a <style> into the Shadow DOM from your renderer — the widget's shadow is mode: 'open', reachable via document.querySelector('#elaras-chat-root').shadowRoot
  • Use attribute styling — the container gets data-loading="true" while an async renderer is pending, which the widget's own stylesheet already dims (opacity: 0.5). You can read that attribute from your renderer and switch classes.

Static skills — no server required

If your skill only needs to emit a fixed set of blocks (a contact form, a menu, a rating prompt) you can skip writing an endpoint entirely. Set source to "static" and put the full response payload in static_response:

{
  "source": "static",
  "static_response": {
    "result": "Here's how to reach us.",
    "_blocks": [
      {
        "type": "elaras.button_group",
        "spec": {
          "buttons": [
            { "label": "Chat with support", "action": "message", "value": "I need help" },
            { "label": "Email us",          "action": "url",     "value": "mailto:hello@example.com" }
          ]
        }
      }
    ]
  }
}

When the agent calls this skill, Elaras returns static_response verbatim — no HTTP call leaves the platform. Useful for fixed menus, demo content, and mock responses during development.