Customize the chat loader

This widget is and is subject to change in minor versions.

The chat widget shows a loader while a chat turn is in progress. The default loader includes a spinner, optional text, and skeleton lines. Use templates.loaderText to change the text or templates.loader to replace the loader. To change when and where the loader renders, see Control when and where the chat loader shows.

Change the loader text

The default loader doesn’t show any text. Add some with templates.loaderText:

JavaScript

chat({
  container: "#chat",
  agentId: "YOUR_AGENT_ID",
  templates: {
    loaderText: "Preparing an answer...",
  },
});

Change the text by turn phase

Pass a function to loaderText to change the text based on the turn context. Use phase to identify the current phase:

Phase	Meaning
`submitted`	The prompt was submitted but no assistant part has arrived yet.
`tool`	Running a tool call, such as a search.
`reasoning`	Reasoning before the answer starts, with `showReasoning` enabled.
`thinking`	Any other pause while the turn is in progress.

JavaScript

chat({
  // ...
  templates: {
    loaderText: ({ phase }) => {
      switch (phase) {
        case "submitted":
          return "Reading your question...";
        case "tool":
          return "Working on your request...";
        case "reasoning":
          return "Working through the details...";
        default:
          return "Writing a response...";
      }
    },
  },
});

The function receives the same turn context as shouldShowLoader, without defaultValue.

Replace the loader

Use the loader template to render your own loading state. It receives:

translations. The resolved loader translations.
context. The same context as loaderText receives.
inline. Whether the loader renders inside an assistant message. It’s true when loaderPosition is message-inline and an assistant message is available.

JavaScript

chat({
  // ...
  templates: {
    loader: ({ context }, { html }) =>
      html`<p>
        ${context.phase === "tool" ? "Searching..." : "Preparing an answer..."}
      </p>`,
  },
});

Use inline if your custom loader needs different markup or spacing when it appears inside a message.

Reuse the default loader

Instead of writing the markup yourself, render the built-in loader with the chatMessageLoader template helper and override what you need. It keeps the default spinner, skeleton lines, and animations. Pass the received properties to chatMessageLoader, then override translations, className, or any element attribute:

JavaScript

import { chatMessageLoader } from "instantsearch.js/es/templates";

chat({
  // ...
  templates: {
    loader: (props) =>
      chatMessageLoader({
        ...props,
        className: "my-Loader",
        translations: { loaderText: "Preparing an answer..." },
      }),
  },
});

Rotate loading messages while the agent is working

Prefer phase, since it tracks the current phase of the turn. For long waits within one phase, cycle through a short set of messages with CSS. Render them all in the template, then fade between them:

JavaScript

chat({
  // ...
  templates: {
    loader: (_, { html }) => html`
      <p class="my-Loader">
        <span>Working on your request...</span>
        <span>Reviewing the results...</span>
        <span>Writing a response...</span>
      </p>
    `,
  },
});

CSS

.my-Loader {
  display: grid;
}

.my-Loader span {
  grid-area: 1 / 1;
  opacity: 0;
  animation: my-Loader-cycle 7.5s infinite;
}

.my-Loader span:nth-child(2) {
  animation-delay: 2.5s;
}

.my-Loader span:nth-child(3) {
  animation-delay: 5s;
}

@keyframes my-Loader-cycle {
  0%,
  33% {
    opacity: 1;
  }
  34%,
  100% {
    opacity: 0;
  }
}

@media (prefers-reduced-motion: reduce) {
  .my-Loader span {
    animation: none;
  }

  .my-Loader span:first-child {
    opacity: 1;
  }
}

Keep each message short, and don’t describe work the agent isn’t doing.

Search and Discovery platform

Optimization and Personalization

AI-powered experiences

Production and scale

Customize the chat loader

Change the loader text

Change the text by turn phase

Replace the loader

Reuse the default loader

Rotate loading messages while the agent is working

​Change the loader text

​Change the text by turn phase

​Replace the loader

​Reuse the default loader

​Rotate loading messages while the agent is working

​Related

Change the loader text

Change the text by turn phase

Replace the loader

Reuse the default loader

Rotate loading messages while the agent is working

Related