# Component Studio

Build custom HTML/CSS/JS components that your AI can render inside chat conversations.

---

Component Studio lets you create custom UI components -- product cards, forms, search results, pricing tables, or anything you can build with HTML, CSS, and JavaScript -- that your AI agent can render directly inside chat conversations. Instead of plain text responses, your chatbot can display rich, interactive interfaces.

## How It Works

Components are self-contained HTML/CSS/JS bundles that run inside a sandboxed iframe within the chat interface. When your AI decides a visual component is the best way to respond, it renders the component with dynamic data passed as props.

```
Consumer: "Show me the top 3 products under $50"
    |
AI selects the "product-card" component
AI passes props: { items: [...], currency: "USD" }
    |
Component renders inside chat as an interactive card grid
```

The AI knows about all components registered to your app, including their name, props schema, and purpose. It decides when to use them based on the conversation context.

## Creating a Component


  **1.** 
    <strong>Open Component Studio</strong>

    Navigate to your app in the builder and click the **Components** tab.
  


  **2.** 
    <strong>Describe your component</strong>

    Open the Alchemist panel and describe what you want to build:

    - "Create a product card component that shows an image, name, price, and an Add to Cart button"
    - "Build a search results list with clickable items and relevance scores"
    - "Make a booking form with date picker, time slots, and a submit button"

    You can also drop a screenshot of a design you want to replicate. The Alchemist generates production-ready HTML, CSS, and JavaScript.
  


  **3.** 
    <strong>Edit and preview</strong>

    The studio shows a split-pane view with tabbed code editors (HTML, CSS, JS) on the left and a live preview on the right. As you edit, the preview updates in real time with a 500ms debounce.
  


  **4.** 
    <strong>Refine with AI</strong>

    Ask the Alchemist to make changes to an existing component:

    - "Add a hover effect to the card"
    - "Make the form responsive for mobile"
    - "Change the color scheme to match our brand"

    The AI-refined code is saved automatically and the component list refreshes.
  


  **5.** 
    <strong>Save</strong>

    Click **Save** to persist your manual edits. The component is immediately available to your AI in conversations.
  


## The Bridge API

Components run inside a sandboxed iframe, but they can communicate back to the chat conversation through the Bridge API on `window.chipp`. This is how components send data, save memories, and trigger actions.

### `window.chipp.actions.submitForm(data)`

Send form data back to the conversation as a user message. The AI sees the data and can respond to it.

```javascript
window.chipp.actions.submitForm({
  name: "Jane Doe",
  email: "jane@example.com"
});
```

### `window.chipp.actions.saveMemory(data)`

Save unstructured text to the user's episodic memory. This text is searched via vector similarity in future conversations.

```javascript
window.chipp.actions.saveMemory(
  "User prefers dark mode and concise answers"
);
```

### `window.chipp.actions.saveToProfile(updates)`

Save structured data to the user's profile (dossier). This data is injected into every future conversation's system prompt. Pass `null` for a field to remove it. Requires a logged-in user.

```javascript
window.chipp.actions.saveToProfile({
  timezone: "America/New_York",
  language: "en",
  preferences: ["dark mode", "concise"],
  notes: "Power user, prefers technical language"
});
```

### `window.chipp.actions.triggerAction(name, data)`

Trigger a named custom action. Sent to the conversation as `[Action: name]` so the AI can respond accordingly.

```javascript
window.chipp.actions.triggerAction("book_appointment", {
  date: "2026-03-15",
  time: "2:00 PM"
});
```

### `window.chipp.props`

Read-only object containing data the AI passes when rendering the component. Use this to populate dynamic content.

```javascript
const { userName, items } = window.chipp.props;
document.getElementById("greeting").textContent =
  "Hello, " + (userName || "there") + "!";
```

## Props Schema

Each component has a props schema that tells the AI what data it can pass. The schema is defined automatically by the Alchemist when it generates the component, or you can view and inspect it in the studio.

| Field | Type | Description |
|-------|------|-------------|
| **name** | string | The prop name (e.g., `items`, `userName`) |
| **type** | string, number, boolean, array, object | The expected data type |
| **description** | string | What this prop contains |
| **required** | boolean | Whether the AI must provide this prop |

The props schema appears as chips below the editor when a component is selected.

## Workspace Sharing

Components can be shared across apps in your workspace or organization. This is useful when you have a common UI pattern (like a product card) that multiple agents need.

### Sharing scopes

| Scope | Visibility |
|-------|-----------|
| **Private** | Only the app that owns the component can use it |
| **Workspace** | All apps in the same workspace can link to this component |
| **Organization** | All apps in any workspace in the organization can link to this component |

Change the sharing scope using the dropdown in the code editor toolbar.

### Linked components

When you share a component at the workspace or organization level, other apps can **link** to it. Linked components appear in the component list with a "Linked" badge and show which app owns them. Linked components are read-only -- edits happen on the original.

To unlink a component from your app, select it and click **Unlink**. This removes it from your app but does not delete the original.

> **Note:** The sharing badge shows how many apps have linked to a shared component (e.g., "Workspace - 3 apps"). This helps you understand the impact before changing or deleting a shared component.

## Component Examples

Here are common component patterns builders create:

| Component | Use Case | Key Props |
|-----------|----------|-----------|
| **Product card** | E-commerce agents showing items | image, name, price, rating |
| **Booking form** | Scheduling assistants | availableDates, timeSlots |
| **Search results** | Knowledge base or catalog search | items, query, totalCount |
| **Pricing table** | Subscription or plan comparison | plans, features, ctaText |
| **Data dashboard** | Analytics or reporting agents | metrics, chartData |
| **Contact form** | Lead capture during conversations | fields, submitLabel |

## Tips for Better Components

1. **Keep it focused**: One component should do one thing well. A product card, not a product-card-with-cart-with-checkout.
2. **Use the Bridge API for interactivity**: Forms should call `submitForm()` so the AI can process the data instead of silently posting elsewhere.
3. **Design for the chat context**: Components render inside message bubbles. Keep widths flexible and avoid fixed pixel widths larger than 400px.
4. **Include fallback text**: If `window.chipp.props` is empty, show placeholder content so the preview remains useful during development.
5. **Share common patterns**: If two apps need the same card layout, create it once and share at the workspace level rather than duplicating code.