Skip to content

The Open Standard for Generative UI

feat(react-ui): native prefill-chips welcome screen (#831)

Ankit Das780bc9795961
diff --git a/packages/react-ui/src/components/AgentInterface/ConversationStarter.tsx b/packages/react-ui/src/components/AgentInterface/ConversationStarter.tsx
index 3b2360a4b..0c3782b5d 100644
--- a/packages/react-ui/src/components/AgentInterface/ConversationStarter.tsx
+++ b/packages/react-ui/src/components/AgentInterface/ConversationStarter.tsx
@@ -9,7 +9,7 @@ import { isChatEmpty } from "./_shared/utils";
export type ConversationStarterVariant = "short" | "long";
interface ConversationStarterItemProps extends ConversationStarterProps {
- onClick: (prompt: string) => void;
+ onClick: () => void;
variant: ConversationStarterVariant;
}
@@ -39,7 +39,6 @@ const hasRenderableIcon = (icon: ReactNode): boolean => {
const ConversationStarterItem = ({
displayText,
- prompt,
onClick,
variant,
icon,
@@ -52,7 +51,7 @@ const ConversationStarterItem = ({
<button
type="button"
className="openui-agent-conversation-starter-item-short"
- onClick={() => onClick(prompt)}
+ onClick={onClick}
>
{shouldRenderIcon && (
<span className="openui-agent-conversation-starter-item-short__icon">{renderedIcon}</span>
@@ -64,11 +63,7 @@ const ConversationStarterItem = ({
// Long variant (detailed list style)
return (
- <button
- type="button"
- className="openui-agent-conversation-starter-item-long"
- onClick={() => onClick(prompt)}
- >
+ <button type="button" className="openui-agent-conversation-starter-item-long" onClick={onClick}>
<div className="openui-agent-conversation-starter-item-long__content">
{shouldRenderIcon && (
<span className="openui-agent-conversation-starter-item-long__icon">{renderedIcon}</span>
@@ -91,23 +86,34 @@ export interface ConversationStarterContainerProps {
* - "long": Vertical list items with icons and hover arrow
*/
variant?: ConversationStarterVariant;
+ /**
+ * Optional click override. When provided, replaces the default
+ * send-to-thread behavior (still guarded by `isRunning`). The prefill-chips
+ * welcome uses it to append contextual-starter prompts into the draft.
+ */
+ onSelect?: (starter: ConversationStarterProps) => void;
}
export const ConversationStarter = ({
starters,
className,
variant = "short",
+ onSelect,
}: ConversationStarterContainerProps) => {
const processMessage = useThread((s) => s.processMessage);
const isRunning = useThread((s) => s.isRunning);
const messages = useThread((s) => s.messages);
const isLoadingMessages = useThread((s) => s.isLoadingMessages);
- const handleClick = (prompt: string) => {
+ const handleClick = (starter: ConversationStarterProps) => {
if (isRunning) return;
+ if (onSelect) {
+ onSelect(starter);
+ return;
+ }
processMessage({
role: "user",
- content: prompt,
+ content: starter.prompt,
});
};
@@ -137,7 +143,7 @@ export const ConversationStarter = ({
displayText={item.displayText}
prompt={item.prompt}
icon={item.icon}
- onClick={handleClick}
+ onClick={() => handleClick(item)}
variant={variant}
/>
))}
@@ -163,7 +169,7 @@ export const ConversationStarter = ({
displayText={item.displayText}
prompt={item.prompt}
icon={item.icon}
- onClick={handleClick}
+ onClick={() => handleClick(item)}
variant={variant}
/>
</Fragment>
diff --git a/packages/react-ui/src/components/AgentInterface/WelcomeScreen.tsx b/packages/react-ui/src/components/AgentInterface/WelcomeScreen.tsx
index 59e6e7cef..9e0046230 100644
--- a/packages/react-ui/src/components/AgentInterface/WelcomeScreen.tsx
+++ b/packages/react-ui/src/components/AgentInterface/WelcomeScreen.tsx
@@ -1,10 +1,12 @@
-import { useThread } from "@openuidev/react-headless";
+import { useThread, useThreadList } from "@openuidev/react-headless";
import clsx from "clsx";
-import { ReactNode } from "react";
+import { ReactNode, useEffect, useRef, useState } from "react";
import { ConversationStarterProps } from "../../types/ConversationStarter";
+import { PrefillChip } from "../../types/PrefillChip";
import { useStartersFromContext } from "./_shared/startersContext";
import { isChatEmpty } from "./_shared/utils";
-import { DesktopWelcomeComposer } from "./components";
+import { appendStarterPrompt } from "./_shared/utils/welcomePrefill";
+import { DesktopWelcomeComposer, WelcomePrefillChips } from "./components";
import { ConversationStarter, ConversationStarterVariant } from "./ConversationStarter";
import { WelcomeGlow, WelcomeGlowProvider } from "./WelcomeGlow";
@@ -43,6 +45,12 @@ interface WelcomeScreenWithContentProps extends WelcomeScreenBaseProps {
* Variant of the conversation starters
*/
starterVariant?: ConversationStarterVariant;
+ /**
+ * Prefill chips rendered between the composer and the starters. Clicking a
+ * chip drops its prompt into the composer (instead of sending) and shows the
+ * chip's contextual starters, which append to the draft.
+ */
+ prefillChips?: PrefillChip[];
/**
* Children are not allowed when using props-based content
*/
@@ -60,6 +68,7 @@ interface WelcomeScreenWithChildrenProps extends WelcomeScreenBaseProps {
image?: never;
starters?: never;
starterVariant?: never;
+ prefillChips?: never;
}
export type WelcomeScreenProps = WelcomeScreenWithContentProps | WelcomeScreenWithChildrenProps;
@@ -79,9 +88,27 @@ export const WelcomeScreen = (props: WelcomeScreenProps) => {
const ownVariant = "starterVariant" in props ? props.starterVariant : undefined;
const starters = ownStarters ?? fromCtx.starters ?? [];
const starterVariant = ownVariant ?? fromCtx.starterVariant ?? "long";
+ const prefillChips = ("prefillChips" in props ? props.prefillChips : undefined) ?? [];
+ const hasChips = prefillChips.length > 0;
const messages = useThread((s) => s.messages);
const isLoadingMessages = useThread((s) => s.isLoadingMessages);
+ const isRunning = useThread((s) => s.isRunning);
+
+ // Prefill-chips draft state — owned here (not in the composer) so chips can
+ // write into the draft. Hooks stay unconditional; unused without chips.
+ const [draft, setDraft] = useState("");
+ const [selectedChip, setSelectedChip] = useState<PrefillChip | null>(null);
+ const inputRef = useRef<HTMLTextAreaElement>(null);
+
+ const selectedThreadId = useThreadList((s) => s.selectedThreadId);
+
+ // The welcome renders unkeyed across thread switches, so a chip-prefilled
+ // draft would otherwise leak into the next empty thread.
+ useEffect(() => {
+ setDraft("");
+ setSelectedChip(null);
+ }, [selectedThreadId]);
// Only show when there are no messages
if (!isChatEmpty({ isLoadingMessages, messages })) {
@@ -118,6 +145,36 @@ export const WelcomeScreen = (props: WelcomeScreenProps) => {
return image;
};
+ const handleDraftChange = (value: string) => {
+ setDraft(value);
+ if (!value) {
+ setSelectedChip(null);
+ }
+ };
+
+ const handleChipClick = (chip: PrefillChip) => {
+ if (isRunning) return;
+ setDraft(chip.prompt);
+ setSelectedChip(chip);
+ const input = inputRef.current;
+ if (!input) return;
+ input.focus();
+ // Caret to the end once React has applied the new value.
+ requestAnimationFrame(() => {
+ input.setSelectionRange(chip.prompt.length, chip.prompt.length);
+ });
+ };
+
+ const handleContextualSelect = (starter: ConversationStarterProps) => {
+ const next = appendStarterPrompt(draft, starter.prompt);
+ setDraft(next);
+ setSelectedChip(null);
+ requestAnimationFrame(() => {
+ inputRef.current?.focus();
+ inputRef.current?.setSelectionRange(next.length, next.length);
+ });
+ };
+
return (
<WelcomeGlowProvider enabled={glowAnimation}>
<div
@@ -144,17 +201,42 @@ export const WelcomeScreen = (props: WelcomeScreenProps) => {
)}
</div>
{/* Desktop-only welcome composer */}
- <div className="openui-agent-welcome-screen__composer-starters-container">
+ <div
+ className="openui-agent-welcome-screen__composer-starters-container"
+ data-has-prefill-chips={(hasChips && draft.length === 0) || undefined}
+ >
<div className="openui-agent-welcome-screen__desktop-composer">
<WelcomeGlow>
- <DesktopWelcomeComposer />
+ {hasChips ? (
+ <DesktopWelcomeComposer
+ value={draft}
+ onChange={handleDraftChange}
+ drafting={draft.length > 0 && !selectedChip}
+ inputRef={inputRef}
+ />
+ ) : (
+ <DesktopWelcomeComposer />
+ )}
</WelcomeGlow>
</div>
- {/* Desktop-only conversation starters */}
- {starters.length > 0 && (
- <div className="openui-agent-welcome-screen__desktop-starters">
- <ConversationStarter starters={starters} variant={starterVariant} />
- </div>
+ {hasChips ? (
+ <WelcomePrefillChips
+ chips={prefillChips}
+ starters={starters}
+ starterVariant={starterVariant}
+ draft={draft}
+ selectedChip={selectedChip}
+ onChipClick={handleChipClick}
+ onContextualSelect={handleContextualSelect}
+ disabled={isRunning}
+ />
+ ) : (
+ /* Desktop-only conversation starters */
+ starters.length > 0 && (
+ <div className="openui-agent-welcome-screen__desktop-starters">
+ <ConversationStarter starters={starters} variant={starterVariant} />
+ </div>
+ )
)}
</div>
</div>
diff --git a/packages/react-ui/src/components/AgentInterface/__tests__/DesktopWelcomeComposer.ssr.test.tsx b/packages/react-ui/src/components/AgentInterface/__tests__/DesktopWelcomeComposer.ssr.test.tsx
new file mode 100644
index 000000000..e0547159b
--- /dev/null
+++ b/packages/react-ui/src/components/AgentInterface/__tests__/DesktopWelcomeComposer.ssr.test.tsx
@@ -0,0 +1,35 @@
+import { ChatProvider } from "@openuidev/react-headless";
+import { renderToString } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { makeMockLLM } from "../../../__test-helpers/mockChat";
+import { DesktopWelcomeComposer } from "../components/DesktopWelcomeComposer";
+
+const render = (ui: React.ReactElement) =>
+ renderToString(<ChatProvider llm={makeMockLLM()}>{ui}</ChatProvider>);
+
+describe("DesktopWelcomeComposer SSR", () => {
+ it("stays uncontrolled by default — empty draft, no drafting attr", () => {
+ const html = render(<DesktopWelcomeComposer />);
+ expect(html).toContain("openui-agent-desktop-welcome-composer");
+ expect(html).not.toContain("data-drafting");
+ });
+
+ it("renders the controlled value", () => {
+ const html = render(
+ <DesktopWelcomeComposer value="Create a presentation about " onChange={() => undefined} />,
+ );
+ expect(html).toContain("Create a presentation about ");
+ });
+
+ it("computes drafting from the controlled value when not overridden", () => {
+ const html = render(<DesktopWelcomeComposer value="hello" onChange={() => undefined} />);
+ expect(html).toContain("data-drafting");
+ });
+
+ it("honors the drafting override (chip-prefilled draft must not fade starters)", () => {
+ const html = render(
+ <DesktopWelcomeComposer value="hello" onChange={() => undefined} drafting={false} />,
+ );
+ expect(html).not.toContain("data-drafting");
+ });
+});
diff --git a/packages/react-ui/src/components/AgentInterface/__tests__/WelcomePrefillChips.ssr.test.tsx b/packages/react-ui/src/components/AgentInterface/__tests__/WelcomePrefillChips.ssr.test.tsx
new file mode 100644
index 000000000..6a4feed16
--- /dev/null
+++ b/packages/react-ui/src/components/AgentInterface/__tests__/WelcomePrefillChips.ssr.test.tsx
@@ -0,0 +1,74 @@
+import { ChatProvider } from "@openuidev/react-headless";
+import { renderToString } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { makeMockLLM } from "../../../__test-helpers/mockChat";
+import type { PrefillChip } from "../../../types/PrefillChip";
+import { WelcomePrefillChips } from "../components/WelcomePrefillChips";
+
+const CHIPS: PrefillChip[] = [
+ {
+ displayText: "Create a presentation",
+ prompt: "Create a presentation about ",
+ starters: [{ displayText: "Our Q2 business review", prompt: "our Q2 business review" }],
+ },
+];
+const STARTERS = [{ displayText: "Quarterly deck", prompt: "Create a Q2 deck." }];
+
+const render = (ui: React.ReactElement) =>
+ renderToString(<ChatProvider llm={makeMockLLM()}>{ui}</ChatProvider>);
+
+describe("WelcomePrefillChips SSR", () => {
+ it("renders the chip row and default starters in layer 1 when draft is empty", () => {
+ const html = render(
+ <WelcomePrefillChips
+ chips={CHIPS}
+ starters={STARTERS}
+ starterVariant="long"
+ draft=""
+ selectedChip={null}
+ onChipClick={() => undefined}
+ onContextualSelect={() => undefined}
+ disabled={false}
+ />,
+ );
+ expect(html).toContain("openui-agent-welcome-screen__starters-layers");
+ expect(html).toContain("openui-agent-welcome-screen__chip-row");
+ expect(html).toContain("openui-agent-prefill-chip");
+ expect(html).toContain("Create a presentation");
+ expect(html).toContain("Quarterly deck");
+ expect(html).not.toContain("data-hidden");
+ });
+
+ it("hides layer 1 when drafting and shows contextual starters for the selected chip", () => {
+ const html = render(
+ <WelcomePrefillChips
+ chips={CHIPS}
+ starters={STARTERS}
+ starterVariant="long"
+ draft="Create a presentation about "
+ selectedChip={CHIPS[0]!}
+ onChipClick={() => undefined}
+ onContextualSelect={() => undefined}
+ disabled={false}
+ />,
+ );
+ expect(html).toContain("data-hidden");
+ expect(html).toContain("Our Q2 business review");
+ });
+
+ it("disables chips while running", () => {
+ const html = render(
+ <WelcomePrefillChips
+ chips={CHIPS}
+ starters={STARTERS}
+ starterVariant="long"
+ draft=""
+ selectedChip={null}
+ onChipClick={() => undefined}
+ onContextualSelect={() => undefined}
+ disabled={true}
+ />,
+ );
+ expect(html).toContain("disabled");
+ });
+});
diff --git a/packages/react-ui/src/components/AgentInterface/__tests__/WelcomeScreen.ssr.test.tsx b/packages/react-ui/src/components/AgentInterface/__tests__/WelcomeScreen.ssr.test.tsx
new file mode 100644
index 000000000..9bc0b8855
--- /dev/null
+++ b/packages/react-ui/src/components/AgentInterface/__tests__/WelcomeScreen.ssr.test.tsx
@@ -0,0 +1,58 @@
+import { ChatProvider } from "@openuidev/react-headless";
+import { renderToString } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { makeMockLLM } from "../../../__test-helpers/mockChat";
+import type { PrefillChip } from "../../../types/PrefillChip";
+import { WelcomeScreen } from "../WelcomeScreen";
+
+const CHIPS: PrefillChip[] = [
+ {
+ displayText: "Create a presentation",
+ prompt: "Create a presentation about ",
+ starters: [{ displayText: "Our Q2 business review", prompt: "our Q2 business review" }],
+ },
+];
+const STARTERS = [{ displayText: "Quarterly deck", prompt: "Create a Q2 deck." }];
+
+const render = (ui: React.ReactElement) =>
+ renderToString(<ChatProvider llm={makeMockLLM()}>{ui}</ChatProvider>);
+
+describe("WelcomeScreen SSR", () => {
+ it("renders chips mode: chip row, layers wrapper, empty-draft container attribute", () => {
+ const html = render(
+ <WelcomeScreen title="Good to see you" starters={STARTERS} prefillChips={CHIPS} />,
+ );
+ expect(html).toContain("data-has-prefill-chips");
+ expect(html).toContain("openui-agent-welcome-screen__starters-layers");
+ expect(html).toContain("openui-agent-welcome-screen__chip-row");
+ expect(html).toContain("openui-agent-prefill-chip");
+ expect(html).toContain("Create a presentation");
+ expect(html).toContain("Quarterly deck");
+ // Initial draft is empty → no drafting fade.
+ expect(html).not.toContain("data-drafting");
+ });
+
+ it("keeps the legacy markup when no chips are passed (back-compat)", () => {
+ const html = render(<WelcomeScreen title="Hi" starters={STARTERS} />);
+ expect(html).toContain("openui-agent-welcome-screen__desktop-starters");
+ expect(html).not.toContain("openui-agent-welcome-screen__starters-layers");
+ expect(html).not.toContain("data-has-prefill-chips");
+ expect(html).not.toContain("openui-agent-prefill-chip");
+ });
+
+ it("treats an empty chips array as absent", () => {
+ const html = render(<WelcomeScreen title="Hi" starters={STARTERS} prefillChips={[]} />);
+ expect(html).not.toContain("openui-agent-welcome-screen__starters-layers");
+ expect(html).not.toContain("data-has-prefill-chips");
+ });
+
+ it("children mode is untouched by chips plumbing", () => {
+ const html = render(
+ <WelcomeScreen>
+ <div>custom welcome</div>
+ </WelcomeScreen>,
+ );
+ expect(html).toContain("custom welcome");
+ expect(html).not.toContain("openui-agent-prefill-chip");
+ });
+});
diff --git a/packages/react-ui/src/components/AgentInterface/__tests__/welcomePrefill.test.ts b/packages/react-ui/src/components/AgentInterface/__tests__/welcomePrefill.test.ts
new file mode 100644
index 000000000..f7ec6b4f9
--- /dev/null
+++ b/packages/react-ui/src/components/AgentInterface/__tests__/welcomePrefill.test.ts
@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { appendStarterPrompt } from "../_shared/utils/welcomePrefill";
+
+describe("appendStarterPrompt", () => {
+ it("returns the prompt alone for an empty draft", () => {
+ expect(appendStarterPrompt("", "our Q2 business review")).toBe("our Q2 business review");
+ });
+
+ it("inserts a single space when the draft lacks a trailing space", () => {
+ expect(appendStarterPrompt("Write a report on", "the EV market")).toBe(
+ "Write a report on the EV market",
+ );
+ });
+
+ it("adds no extra space when the draft already ends with one", () => {
+ expect(appendStarterPrompt("Create a presentation about ", "a product launch plan")).toBe(
+ "Create a presentation about a product launch plan",
+ );
+ });
+});
diff --git a/packages/react-ui/src/components/AgentInterface/_shared/utils/welcomePrefill.ts b/packages/react-ui/src/components/AgentInterface/_shared/utils/welcomePrefill.ts
new file mode 100644
index 000000000..1468a1fd4
--- /dev/null
+++ b/packages/react-ui/src/components/AgentInterface/_shared/utils/welcomePrefill.ts
@@ -0,0 +1,9 @@
+/**
+ * Joins a contextual-starter prompt onto the current draft, inserting a single
+ * space separator unless the draft is empty or already ends with a space.
+ * (Prefill chips end their prompt with a trailing space on purpose.)
+ */
+export const appendStarterPrompt = (draft: string, prompt: string): string => {
+ const separator = draft.length > 0 && !draft.endsWith(" ") ? " " : "";
+ return `${draft}${separator}${prompt}`;
+};
diff --git a/packages/react-ui/src/components/AgentInterface/agentInterface.scss b/packages/react-ui/src/components/AgentInterface/agentInterface.scss
index dcaba301e..d1cd612ce 100644
--- a/packages/react-ui/src/components/AgentInterface/agentInterface.scss
+++ b/packages/react-ui/src/components/AgentInterface/agentInterface.scss
@@ -8,6 +8,7 @@
@use "./welcomeScreen.scss";
@use "./welcomeGlow.scss";
@use "./components/desktopWelcomeComposer.scss";
+@use "./components/welcomePrefillChips.scss";
@use "./components/composer.scss";
@use "./artifactBrowser.scss";
@use "./workspaceSidebar.scss";
diff --git a/packages/react-ui/src/components/AgentInterface/components/DesktopWelcomeComposer.tsx b/packages/react-ui/src/components/AgentInterface/components/DesktopWelcomeComposer.tsx
index 4c536ecb1..683e4c621 100644
--- a/packages/react-ui/src/components/AgentInterface/components/DesktopWelcomeComposer.tsx
+++ b/packages/react-ui/src/components/AgentInterface/components/DesktopWelcomeComposer.tsx
@@ -1,7 +1,7 @@
import { useThread, useThreadList } from "@openuidev/react-headless";
import clsx from "clsx";
import { ArrowUp, Square } from "lucide-react";
-import { useLayoutEffect, useRef } from "react";
+import { RefObject, useLayoutEffect, useRef } from "react";
import { useLayoutContext } from "../../../context/LayoutContext";
import { useAutoFocus } from "../../../hooks/useAutoFocus";
import { useComposerState } from "../../../hooks/useComposerState";
@@ -10,22 +10,45 @@ import { IconButton } from "../../IconButton";
export interface DesktopWelcomeComposerProps {
className?: string;
placeholder?: string;
+ /**
+ * Controlled draft value. When set, the internal draft state is bypassed and
+ * `onChange` receives every edit (including the clear on submit). Used by the
+ * prefill-chips welcome, whose chips must write into the draft.
+ */
+ value?: string;
+ onChange?: (value: string) => void;
+ /**
+ * Overrides the internal `data-drafting` computation (value non-empty). The
+ * prefill-chips welcome passes `false` for chip-prefilled drafts so the
+ * contextual starters below don't fade.
+ */
+ drafting?: boolean;
+ /** Ref to the underlying textarea, for focus/caret placement by the owner. */
+ inputRef?: RefObject<HTMLTextAreaElement | null>;
}
export const DesktopWelcomeComposer = ({
className,
placeholder = "Type your query here",
+ value,
+ onChange,
+ drafting,
+ inputRef,
}: DesktopWelcomeComposerProps) => {
- const { textContent, setTextContent } = useComposerState();
+ const internal = useComposerState();
+ const isControlled = value !== undefined;
+ const textContent = isControlled ? value : internal.textContent;
+ const setTextContent = isControlled ? (onChange ?? (() => undefined)) : internal.setTextContent;
const processMessage = useThread((s) => s.processMessage);
const cancelMessage = useThread((s) => s.cancelMessage);
const isRunning = useThread((s) => s.isRunning);
const isLoadingMessages = useThread((s) => s.isLoadingMessages);
- const inputRef = useRef<HTMLTextAreaElement>(null);
+ const ownRef = useRef<HTMLTextAreaElement>(null);
+ const textareaRef = inputRef ?? ownRef;
const selectedThreadId = useThreadList((s) => s.selectedThreadId);
const { layout } = useLayoutContext();
- useAutoFocus(inputRef, {
+ useAutoFocus(textareaRef, {
enabled: layout !== "mobile" && !isLoadingMessages,
focusKey: selectedThreadId,
});
@@ -44,21 +67,21 @@ export const DesktopWelcomeComposer = ({
};
useLayoutEffect(() => {
- const input = inputRef.current;
+ const input = textareaRef.current;
if (!input) return;
// Reset to 0 (not "auto") so scrollHeight reflects content, not container
input.style.height = "0px";
input.style.height = `${Math.max(input.scrollHeight, 24)}px`;
- }, [textContent]);
+ }, [textContent, textareaRef]);
return (
<div
className={clsx("openui-agent-desktop-welcome-composer", className)}
- data-drafting={textContent.length > 0 || undefined}
+ data-drafting={(drafting ?? textContent.length > 0) || undefined}
>
<textarea
- ref={inputRef}
+ ref={textareaRef}
value={textContent}
onChange={(e) => setTextContent(e.target.value)}
className="openui-agent-desktop-welcome-composer__input"
diff --git a/packages/react-ui/src/components/AgentInterface/components/WelcomePrefillChips.tsx b/packages/react-ui/src/components/AgentInterface/components/WelcomePrefillChips.tsx
new file mode 100644
index 000000000..99bdfc9c8
--- /dev/null
+++ b/packages/react-ui/src/components/AgentInterface/components/WelcomePrefillChips.tsx
@@ -0,0 +1,83 @@
+import { ConversationStarterProps } from "../../../types/ConversationStarter";
+import { PrefillChip } from "../../../types/PrefillChip";
+import { ConversationStarter, ConversationStarterVariant } from "../ConversationStarter";
+
+interface PrefillChipButtonProps {
+ chip: PrefillChip;
+ disabled: boolean;
+ onClick: () => void;
+}
+
+const PrefillChipButton = ({ chip, disabled, onClick }: PrefillChipButtonProps) => (
+ <button type="button" className="openui-agent-prefill-chip" disabled={disabled} onClick={onClick}>
+ {chip.icon && (
+ <span className="openui-agent-prefill-chip__icon" aria-hidden>
+ {chip.icon}
+ </span>
+ )}
+ <span className="openui-agent-prefill-chip__label">{chip.displayText}</span>
+ </button>
+);
+
+export interface WelcomePrefillChipsProps {
+ chips: PrefillChip[];
+ starters: ConversationStarterProps[];
+ starterVariant: ConversationStarterVariant;
+ draft: string;
+ selectedChip: PrefillChip | null;
+ onChipClick: (chip: PrefillChip) => void;
+ onContextualSelect: (starter: ConversationStarterProps) => void;
+ disabled: boolean;
+}
+
+/**
+ * Chip row + grid-stacked starters layers for the prefill-chips welcome.
+ * Layer 1 (chips + default starters) hides via `visibility` while drafting so
+ * the layout doesn't jump; layer 2 shows the selected chip's contextual
+ * starters, which append to the draft (see WelcomeScreen).
+ */
+export const WelcomePrefillChips = ({
+ chips,
+ starters,
+ starterVariant,
+ draft,
+ selectedChip,
+ onChipClick,
+ onContextualSelect,
+ disabled,
+}: WelcomePrefillChipsProps) => {
+ const isDraftEmpty = draft.length === 0;
+
+ return (
+ <div className="openui-agent-welcome-screen__desktop-starters openui-agent-welcome-screen__starters-layers">
+ <div
+ className="openui-agent-welcome-screen__starters-layer"
+ data-hidden={!isDraftEmpty || undefined}
+ aria-hidden={!isDraftEmpty || undefined}
+ >
+ <div className="openui-agent-welcome-screen__chip-row">
+ {chips.map((chip, index) => (
+ <PrefillChipButton
+ key={`${chip.displayText}-${index}`}
+ chip={chip}
+ disabled={disabled}
+ onClick={() => onChipClick(chip)}
+ />
+ ))}
+ </div>
+ <ConversationStarter starters={starters} variant={starterVariant} />
+ </div>
+ {selectedChip && (
+ <div className="openui-agent-welcome-screen__starters-layer">
+ <ConversationStarter
+ starters={selectedChip.starters}
+ variant="long"
+ onSelect={onContextualSelect}
+ />
+ </div>
+ )}
+ </div>
+ );
+};
+
+export default WelcomePrefillChips;
diff --git a/packages/react-ui/src/components/AgentInterface/components/index.ts b/packages/react-ui/src/components/AgentInterface/components/index.ts
index b3792db6d..bdbf1525a 100644
--- a/packages/react-ui/src/components/AgentInterface/components/index.ts
+++ b/packages/react-ui/src/components/AgentInterface/components/index.ts
@@ -1,2 +1,3 @@
export * from "./Composer";
export * from "./DesktopWelcomeComposer";
+export * from "./WelcomePrefillChips";
diff --git a/packages/react-ui/src/components/AgentInterface/components/welcomePrefillChips.scss b/packages/react-ui/src/components/AgentInterface/components/welcomePrefillChips.scss
new file mode 100644
index 000000000..e093ad33b
--- /dev/null
+++ b/packages/react-ui/src/components/AgentInterface/components/welcomePrefillChips.scss
@@ -0,0 +1,80 @@
+@use "../../../cssUtils" as cssUtils;
+
+// Prefill-chips welcome: grid-stacked starters layers (chips mode only).
+// Layer 1 = chip row + default starters; layer 2 = the selected chip's
+// contextual starters. Layers overlap via grid-area so swapping them never
+// shifts the composer above.
+.openui-agent-welcome-screen__starters-layers {
+ display: grid;
+ align-items: start;
+ width: 100%;
+}
+
+.openui-agent-welcome-screen__starters-layer {
+ display: flex;
+ grid-area: 1 / 1;
+ flex-direction: column;
+ align-items: center;
+ gap: cssUtils.$space-2xl;
+ width: 100%;
+
+ &[data-hidden] {
+ visibility: hidden;
+ pointer-events: none;
+ }
+}
+
+.openui-agent-welcome-screen__chip-row {
+ display: flex;
+ justify-content: flex-start;
+ flex-wrap: wrap;
+ gap: cssUtils.$space-s;
+ width: 100%;
+ max-width: 768px;
+}
+
+.openui-agent-prefill-chip {
+ appearance: none;
+ display: inline-flex;
+ align-items: center;
+ gap: cssUtils.$space-xs;
+ padding: cssUtils.$space-s cssUtils.$space-m;
+ border: 1px solid cssUtils.$border-interactive;
+ border-radius: cssUtils.$radius-full;
+ background: cssUtils.$highlight-subtle;
+ color: cssUtils.$text-neutral-secondary;
+ @include cssUtils.typography(label, small);
+ cursor: pointer;
+ transition:
+ background-color 0.15s ease,
+ border-color 0.15s ease,
+ box-shadow 0.15s ease,
+ color 0.15s ease;
+
+ &:not(:disabled):hover {
+ background: cssUtils.$highlight;
+ border-color: cssUtils.$border-interactive-emphasis;
+ color: cssUtils.$text-neutral-primary;
+ }
+
+ &:focus-visible {
+ outline: none;
+ box-shadow: 0 0 0 2.5px cssUtils.$border-default;
+ }
+
+ &:disabled {
+ cursor: default;
+ opacity: 0.5;
+ }
+
+ &__icon {
+ display: inline-flex;
+ align-items: center;
+ justify-content: center;
+ flex-shrink: 0;
+ }
+
+ &__label {
+ white-space: nowrap;
+ }
+}
diff --git a/packages/react-ui/src/components/AgentInterface/stories/AgentInterface.stories.tsx b/packages/react-ui/src/components/AgentInterface/stories/AgentInterface.stories.tsx
index c15c630f9..b983a7e8c 100644
--- a/packages/react-ui/src/components/AgentInterface/stories/AgentInterface.stories.tsx
+++ b/packages/react-ui/src/components/AgentInterface/stories/AgentInterface.stories.tsx
@@ -2,8 +2,10 @@ import type { Message } from "@openuidev/react-headless";
import {
ArrowLeft,
BookOpen,
+ FileText,
HelpCircle,
MessageSquare,
+ Presentation as PresentationIcon,
Settings,
Share,
Sparkles,
@@ -12,6 +14,7 @@ import {
} from "lucide-react";
import { useState } from "react";
import { makeMockLLM, makeMockStorage, mockSSEResponse } from "../../../__test-helpers/mockChat";
+import type { PrefillChip } from "../../../types/PrefillChip";
import { Button } from "../../Button";
import { IconButton } from "../../IconButton";
import { AgentInterface } from "../AgentInterface";
@@ -113,6 +116,41 @@ const LONG_STARTERS = [
},
];
+const PREFILL_CHIPS: PrefillChip[] = [
+ {
+ displayText: "Create a presentation",
+ prompt: "Create a presentation about ",
+ icon: <PresentationIcon size={16} />,
+ starters: [
+ { displayText: "Our Q2 business review", prompt: "our Q2 business review", icon: <></> },
+ { displayText: "A product launch plan", prompt: "a product launch plan", icon: <></> },
+ {
+ displayText: "The future of electric vehicles",
+ prompt: "the future of electric vehicles",
+ icon: <></>,
+ },
+ ],
+ },
+ {
+ displayText: "Write a report",
+ prompt: "Write a report on ",
+ icon: <FileText size={16} />,
+ starters: [
+ { displayText: "The EV market in 2026", prompt: "the EV market in 2026", icon: <></> },
+ {
+ displayText: "Our quarterly performance",
+ prompt: "our quarterly performance",
+ icon: <></>,
+ },
+ {
+ displayText: "Enterprise adoption of AI",
+ prompt: "enterprise adoption of AI",
+ icon: <></>,
+ },
+ ],
+ },
+];
+
export default {
title: "Components/AgentInterface",
tags: ["dev"],
@@ -215,6 +253,27 @@ export const WithWelcome = {
),
};
+/** Welcome with prefill chips — chip click prefills the composer; contextual starters append. */
+export const WelcomeWithPrefillChips = {
+ render: () => (
+ <AgentInterface
+ storage={emptyStorage}
+ llm={echoLLM}
+ logoUrl={logoUrl}
+ agentName="OpenUI Assistant"
+ starters={LONG_STARTERS}
+ starterVariant="long"
+ >
+ <AgentInterface.Welcome
+ title="Good to see you"
+ description="What's on your mind today?"
+ prefillChips={PREFILL_CHIPS}
+ glowAnimation
+ />
+ </AgentInterface>
+ ),
+};
+
/** Composer-only starters (no Welcome) — chips above the input. */
export const ComposerStarters = {
render: () => (
diff --git a/packages/react-ui/src/components/AgentInterface/welcomeScreen.scss b/packages/react-ui/src/components/AgentInterface/welcomeScreen.scss
index 5e93f0dd7..a999b6709 100644
--- a/packages/react-ui/src/components/AgentInterface/welcomeScreen.scss
+++ b/packages/react-ui/src/components/AgentInterface/welcomeScreen.scss
@@ -88,6 +88,18 @@ $center-align-spacing: calc(32px + cssUtils.$space-s);
width: 100%;
}
+ // Prefill-chips welcome (chips mode only): tighter gap while the chip row
+ // is visible; when drafting hides the layers, collapse the reserved space.
+ // Scoped by __starters-layers so welcomes without chips are unaffected.
+ &__composer-starters-container[data-has-prefill-chips] {
+ gap: cssUtils.$space-l;
+ }
+
+ &__composer-starters-container:not([data-has-prefill-chips])
+ .openui-agent-welcome-screen__starters-layers {
+ margin-bottom: calc(cssUtils.$space-l - cssUtils.$space-2xl);
+ }
+
// Desktop welcome composer container
&__desktop-composer {
display: flex;
diff --git a/packages/react-ui/src/index.ts b/packages/react-ui/src/index.ts
index 86d51f189..0583f076a 100644
--- a/packages/react-ui/src/index.ts
+++ b/packages/react-ui/src/index.ts
@@ -130,3 +130,4 @@ export type {
ConversationStarterIcon,
ConversationStarterProps,
} from "./types/ConversationStarter";
+export type { PrefillChip } from "./types/PrefillChip";
diff --git a/packages/react-ui/src/types/PrefillChip.ts b/packages/react-ui/src/types/PrefillChip.ts
new file mode 100644
index 000000000..68435a33f
--- /dev/null
+++ b/packages/react-ui/src/types/PrefillChip.ts
@@ -0,0 +1,16 @@
+import { ReactNode } from "react";
+import { ConversationStarterProps } from "./ConversationStarter";
+
+/**
+ * A ChatGPT-style prefill chip for the welcome screen: clicking drops
+ * `prompt` into the welcome composer (instead of sending), then shows the
+ * chip's contextual `starters`, which append to the draft on click.
+ */
+export interface PrefillChip {
+ displayText: string;
+ prompt: string;
+ /** Optional icon; omit for none (chips render no default icon). */
+ icon?: ReactNode;
+ /** Contextual starters shown after this chip prefills the composer. */
+ starters: ConversationStarterProps[];
+}