AI chat¶

Usage¶

AI chat is useful when users describe tasks in their own words and expect structured responses or guidance.

When to use¶

• For tasks that are complex, open-ended, or benefit from iteration.
• When natural language input improves user experience.
• When users need help without navigating multiple UI elements.

Best practices¶

• Refer to conversational design guidelines.
• Always allow users to review, edit, or retry.
• Keep the conversation focused, avoid unnecessary messages.
• Place the AI in a clearly defined visual space.
• Output can be styled as needed using the typography system.
• Use follow-up prompts after AI responses to help users continue the conversation without formulating the next message from scratch.

Design¶

Elements¶

1. Chat input
2. Chat message - AI
3. Chat message- User

Layouts¶

Full page layout¶

Use it when AI is the main feature. Typically triggered from a dedicated navigation item, this layout makes AI functionality easily accessible as a primary experience.

The chat content area has a maximum width of 720px. It scales fluidly on smaller screens and remains centered on larger ones to maintain readability and visual balance.

Side panel layout¶

Use it when AI supports tasks within the current view. In this case, the AI appears as an on-demand assistant without disrupting the workflow in a side panel.

• When the AI feature is globally accessible, the side panel can be triggered from the application header, ensuring consistent entry across all screens.
• For contextual use, place the trigger near the related feature or content.

Initial screen¶

Before the first message, show an initial screen to set expectations and explain what the AI can do. As soon as the user prompts a message, the initial screen should disappear.

1. AI icon
2. Salutation: A brief, welcoming message that sets a conversational tone.
3. Prompt categories (optional): When suggestions exceed a manageable number, group them by topic or function using summary chips
4. Prompt suggestions (optional): Curated prompts or example questions that reflect common or relevant actions.
5. Chat input

Errors and AI limitations¶

System errors, such as timeouts or backend crashes, occur outside the AI’s reasoning. These should be represented with inline notifications, placed above the input prompt.

When the AI cannot complete a task due to a known limitation, it should respond within the conversation. These are not treated as errors and do not require a separate notification.

Follow-up prompts¶

Follow-up prompts are 2-4 suggested actions based on the AI’s last response. They guide users toward deeper or related questions.

Show follow-up prompts only after relevant AI responses, and clear them as soon as the user sends a new message.

1. Follow-up prompts

Code¶

The si-ai-chat component provides a complete AI chat interface, it should be inserted into a layout with fixed height, if no fixed height is provided, please set a height in pixels.

SiAiChatComponent API Documentation¶

A model-driven chat container component for displaying an AI chat interface with automatic scroll-to-bottom behavior.

This component provides an AI chat interface, managing scrolling behavior to keep the newest messages visible while respecting user scrolling actions. It automatically scrolls to the bottom when new content is added, unless the user has scrolled up to view older messages.

Required content projection: - si-chat-input : Input controls for composing messages

See - ChatMessage for the chat message model - AiChatMessage for the AI chat message model - UserChatMessage for the user chat message model - TemplateChatMessage for the template chat message model - SiChatInputComponent for the chat input component - SiChatContainerComponent for the base chat container component - SiAiMessageComponent for the used AI message component - SiUserMessageComponent for the used user message component - SiChatMessageComponent for the base wrapper chat message component used by AI and user message components

Input Properties¶

Output Properties¶

Attributes and Methods¶

Use type: 'activity' for tool calls, progress, and reasoning. input accepts a string, a list of short inputs, or a record of labeled inputs. output accepts a string. These values are rendered as activity message parts, while content is rendered directly as markdown. Prefer content when the activity does not need separate input and output sections.

Use type: 'activity-trace' to group related or nested activity messages. By default, the latest activity or trace stays expanded until a newer activity or user message is added. Set the container's autoExpand input to change this globally, or set autoExpand on a trace, activity, or nested activity to override it. Use autoExpandInputs and autoExpandOutputs for part-level overrides; autoExpandInputs also accepts an array of record keys.

The container's show input controls which parts are rendered. It accepts auto, inputs, outputs, or both. The default auto mode shows inputs when output is empty and otherwise shows the output.

Initial Screen¶

The AI chat container includes a built-in initial welcome screen component that displays when there are no messages. It can be slotted into the si-chat-container component. It accepts prompt suggestions as an input.

SiAiWelcomeScreenComponent API Documentation¶

AI welcome screen component for displaying initial state in AI chat interfaces.

The AI welcome screen component provides an engaging initial state for AI chat interfaces, featuring a welcome message, optional prompt categories for filtering, and suggested prompts that users can click to start conversations.

The component includes: - Welcome header with AI branding and customizable greeting - Optional category pills for filtering prompt suggestions - Clickable prompt suggestion cards - Optional refresh button to regenerate suggestions

See - SiAiChatComponent for the AI chat container which uses this component - SiChatContainerComponent for the base chat container

Input Properties¶

Output Properties¶

Prompt Suggestions¶

Prompt suggestions can be provided as either:

• A simple array of suggestions (no categories)
• A record mapping category labels to arrays of suggestions

When using a record, categories are automatically displayed as filter pills.

// Simple array (no categories)
promptSuggestions = [
  { text: 'How do I optimize performance?' },
  { text: 'What are best practices?' }
];

// Record with categories
promptSuggestions = {
  'All prompts': [{ text: 'How do I optimize performance?' }, { text: 'What are best practices?' }],
  'Maintenance': [{ text: 'Schedule preventive maintenance' }, { text: 'Track equipment downtime' }]
};

Base Chat Container¶

Use this base container with the chat messages to build custom chat message interfaces.

The si-chat-container component is a wrapper component, it has slots for chat messages and a chat input.

The slots are:

• default -> chat messages or initial screen (si-welcome-screen)
• si-chat-input/siChatContainerInput (helper directive) -> For the input (whether default or custom).
• si-inline-notification -> Slotted above the input for displaying the status.

SiChatContainerComponent API Documentation¶

A declarative container component for displaying a chat interface with automatic scroll-to-bottom behavior.

This component provides the layout and styling for a chat interface, managing scrolling behavior to keep the newest messages visible while respecting user scrolling actions. It automatically scrolls to the bottom when new content is added, unless the user has scrolled up to view older messages.

Use via content projection: - Default content: Chat messages displayed in the scrollable messages container or a welcome screen (empty state). - si-inline-notification selector: Notification component displayed above the input area - si-chat-input or [siChatContainerInput] selector: Input controls for composing messages

See - SiChatInputComponent for the chat input wrapper component - SiChatContainerInputDirective for other input controls to slot in - SiAiMessageComponent for AI messages to slot in - SiUserMessageComponent for user messages (in AI chats) to slot in - SiChatMessageComponent for the chat message wrapper component to slot in other messages

Input Properties¶

Attributes and Methods¶

Initial Screen¶

When initially displaying a chat interface use the initial si-welcome-screen component that displays when there are no messages. It can be slotted into the si-chat-container component. It accepts prompt suggestions as an input.

SiAiWelcomeScreenComponent API Documentation¶

AI welcome screen component for displaying initial state in AI chat interfaces.

The AI welcome screen component provides an engaging initial state for AI chat interfaces, featuring a welcome message, optional prompt categories for filtering, and suggested prompts that users can click to start conversations.

The component includes: - Welcome header with AI branding and customizable greeting - Optional category pills for filtering prompt suggestions - Clickable prompt suggestion cards - Optional refresh button to regenerate suggestions

See - SiAiChatComponent for the AI chat container which uses this component - SiChatContainerComponent for the base chat container

Input Properties¶

Output Properties¶

Types Documentation¶

import { siMarkdownMathKaTeX } from '@siemens/element-ng/markdown/extensions/math';
import remarkGemoji from 'remark-gemoji';

protected markdownOptions = new SiMarkdownOptions()
  .installExtension(siMarkdownMathKaTeX())
  .installUnifiedPlugin(remarkGemoji);

<si-markdown [markdown]="markdownText()" [options]="markdownOptions" />

<si-chat-input>
  <div siChatInputDisclaimer>
    Custom disclaimer content
  </div>
</si-chat-input>

<si-chat-container>
  <si-chat-message>Hello!</si-chat-message>
  <si-chat-message>How are you?</si-chat-message>

  <input siChatContainerInput type="text" placeholder="Type a message..." />
</si-chat-container>