Dynamic UI Component Usage Guide

This guide provides comprehensive instructions for AI models on how to use the dynamic-ui component to create interactive user interfaces.

🆕 NEW FEATURES: Interactive Forms & Functional Charts

Interactive Forms with Data Capture

Forms now capture user input and automatically pass it to your next API call:

<dynamic-ui layout="form" title="Contact Form" sections='[
  {"type": "header", "title": "Get in Touch"},
  {"type": "input", "name": "name", "label": "Your Name", "placeholder": "Enter your name", "required": true},
  {"type": "input", "name": "email", "label": "Email", "placeholder": "your@email.com", "required": true},
  {"type": "textarea", "name": "message", "label": "Message", "placeholder": "Your message...", "required": true},
  {"type": "select", "name": "topic", "label": "Topic", "options": [
    {"label": "General Inquiry", "value": "general"},
    {"label": "Support", "value": "support"},
    {"label": "Sales", "value": "sales"}
  ]},
  {"type": "checkbox", "name": "newsletter", "label": "Subscribe to newsletter"},
  {"type": "submit", "text": "Send Message", "color": "blue"}
]' />

How it works:

User fills out the form
User clicks Submit
Form data is automatically prepended to their next message
You receive: Form Data: [name: John Smith, email: john@example.com, message: Hello...]\n\nUser's actual message

Functional Charts with Real Data

Charts now display actual data instead of placeholders:

<dynamic-ui layout="dashboard" sections='[
  {
    "type": "chart",
    "title": "Monthly Sales",
    "chartType": "bar",
    "chartData": [
      {"label": "Jan", "value": 4500, "color": "#3b82f6"},
      {"label": "Feb", "value": 6200, "color": "#10b981"},
      {"label": "Mar", "value": 5800, "color": "#f59e0b"},
      {"label": "Apr", "value": 7200, "color": "#ef4444"}
    ],
    "showLabels": true,
    "showValues": true
  }
]' />

Chart Types Available:

bar - Horizontal bar chart
line - Line chart with points
pie - Pie chart with segments

Overview

The dynamic-ui component allows you to generate interactive UI elements using a template-based approach. It supports various layouts, themes, and a comprehensive library of component types.

Basic Syntax

<dynamic-ui 
  layout="dashboard" 
  theme="modern" 
  title="My Dashboard"
  sections='[{"type": "header", "title": "Welcome"}, {"type": "text", "content": "Hello world"}]'
/>

Component Properties

Main Properties

layout: Layout type - card, dashboard, form, list, grid, report
theme: Visual theme - modern, minimal, classic
title: Optional title for the entire UI
sections: JSON array of UI sections (see Section Types below)

Layout Types

Dashboard Layout

<dynamic-ui layout="dashboard" title="Sales Dashboard" sections='[
  {"type": "metric", "label": "Revenue", "value": "$45,231", "trend": "+12%", "color": "green"},
  {"type": "metric", "label": "Users", "value": "1,234", "trend": "+5%", "color": "blue"},
  {"type": "chart", "title": "Monthly Sales", "data": []}
]' />

Form Layout

<dynamic-ui layout="form" title="User Registration" sections='[
  {"type": "header", "title": "Create Account", "size": "medium"},
  {"type": "text", "content": "Please fill in your details below"},
  {"type": "button", "text": "Submit", "variant": "default", "color": "blue"}
]' />

Card Layout

<dynamic-ui layout="card" sections='[
  {"type": "header", "title": "Product Info"},
  {"type": "text", "content": "Product description here"},
  {"type": "badge-group", "badges": [{"text": "New", "color": "green"}, {"text": "Featured"}]}
]' />

Section Types Reference

1. Header

{
  "type": "header",
  "title": "Main Title",
  "size": "large|medium|small",
  "color": "blue|green|red|yellow|purple|gray|orange"
}

2. Text

{
  "type": "text",
  "content": "Text content here",
  "size": "large|medium|small"
}

3. Metric Cards

{
  "type": "metric",
  "label": "Revenue",
  "value": "$45,231",
  "trend": "+12%",
  "color": "green"
}

4. Charts (Enhanced with Real Data)

{
  "type": "chart",
  "title": "Sales Chart",
  "chartType": "bar|line|pie",
  "chartData": [
    {"label": "Q1", "value": 100, "color": "#3b82f6"},
    {"label": "Q2", "value": 150, "color": "#10b981"}
  ],
  "showLabels": true,
  "showValues": true
}

5. Form Inputs

5a. Text Input

{
  "type": "input",
  "name": "fieldName",
  "label": "Field Label",
  "placeholder": "Enter text...",
  "required": true,
  "defaultValue": "initial value"
}

5b. Textarea

{
  "type": "textarea",
  "name": "message",
  "label": "Message",
  "placeholder": "Enter your message...",
  "required": false
}

{
  "type": "select",
  "name": "category",
  "label": "Category",
  "placeholder": "Choose category",
  "options": [
    {"label": "Option 1", "value": "opt1"},
    {"label": "Option 2", "value": "opt2"}
  ],
  "required": true
}

5d. Checkbox

{
  "type": "checkbox",
  "name": "agree",
  "label": "I agree to terms",
  "defaultValue": false
}

5e. Submit Button

{
  "type": "submit",
  "text": "Submit Form",
  "color": "blue",
  "size": "medium"
}

6. Buttons

{
  "type": "button",
  "text": "Click Me",
  "variant": "default|secondary|destructive|outline",
  "size": "small|medium|large",
  "color": "blue"
}

7. Cards

{
  "type": "card",
  "title": "Card Title",
  "content": "Card content",
  "items": []
}

8. Grid Layout

{
  "type": "grid",
  "columns": 2,
  "items": [
    {"type": "text", "content": "Item 1"},
    {"type": "text", "content": "Item 2"}
  ]
}

9. Lists

{
  "type": "list",
  "items": [
    {"text": "Item 1"},
    {"text": "Item 2"},
    {"text": "Item 3"}
  ]
}

10. Progress Bars

{
  "type": "progress",
  "label": "Progress",
  "percentage": 75
}

11. Alerts

{
  "type": "alert",
  "text": "Important message",
  "alertType": "info|warning|error|success"
}

12. Separators

{
  "type": "separator"
}

13. Badge Groups

{
  "type": "badge-group",
  "badges": [
    {"text": "New", "color": "green"},
    {"text": "Featured", "color": "blue"}
  ]
}

Complete Examples

Example 1: Sales Dashboard

<dynamic-ui layout="dashboard" title="Sales Dashboard" theme="modern" sections='[
  {
    "type": "grid",
    "columns": 3,
    "items": [
      {
        "type": "metric",
        "label": "Total Revenue",
        "value": "$124,532",
        "trend": "+15.3%",
        "color": "green"
      },
      {
        "type": "metric",
        "label": "New Customers",
        "value": "846",
        "trend": "+8.2%",
        "color": "blue"
      },
      {
        "type": "metric",
        "label": "Conversion Rate",
        "value": "3.7%",
        "trend": "-2.1%",
        "color": "red"
      }
    ]
  },
  {
    "type": "separator"
  },
  {
    "type": "chart",
    "title": "Monthly Performance",
    "data": [45, 52, 48, 61, 55, 67]
  },
  {
    "type": "alert",
    "text": "Sales target achieved for this quarter!",
    "alertType": "success"
  }
]' />

Example 2: User Profile Form

<dynamic-ui layout="form" title="User Profile" theme="minimal" sections='[
  {
    "type": "header",
    "title": "Edit Profile",
    "size": "large"
  },
  {
    "type": "text",
    "content": "Update your personal information below."
  },
  {
    "type": "card",
    "title": "Personal Details",
    "content": "This section contains your personal information that will be visible to other users."
  },
  {
    "type": "badge-group",
    "badges": [
      {"text": "Verified", "color": "green"},
      {"text": "Premium", "color": "purple"}
    ]
  },
  {
    "type": "button",
    "text": "Save Changes",
    "variant": "default",
    "color": "blue"
  }
]' />

Example 3: Project Status Report

<dynamic-ui layout="report" title="Project Status" sections='[
  {
    "type": "header",
    "title": "Q4 Project Report",
    "size": "large",
    "color": "blue"
  },
  {
    "type": "grid",
    "columns": 2,
    "items": [
      {
        "type": "card",
        "title": "Completed Tasks",
        "items": [
          {
            "type": "progress",
            "label": "Backend Development",
            "percentage": 95
          },
          {
            "type": "progress",
            "label": "Frontend Design",
            "percentage": 78
          },
          {
            "type": "progress",
            "label": "Testing",
            "percentage": 45
          }
        ]
      },
      {
        "type": "card",
        "title": "Team Metrics",
        "items": [
          {
            "type": "metric",
            "label": "Team Members",
            "value": "8",
            "color": "blue"
          },
          {
            "type": "metric",
            "label": "Hours Logged",
            "value": "1,247",
            "color": "green"
          }
        ]
      }
    ]
  },
  {
    "type": "list",
    "items": [
      {"text": "✅ Database migration completed"},
      {"text": "✅ API endpoints implemented"},
      {"text": "⏳ Frontend integration in progress"},
      {"text": "📅 User testing scheduled for next week"}
    ]
  }
]' />

Best Practices

1. Layout Selection

Dashboard: Use for data-heavy interfaces with metrics and charts
Form: Use for input-focused interfaces
Card: Use for content presentation
Report: Use for detailed information display

2. Color Usage

Blue: Primary actions, information
Green: Success, positive metrics, growth
Red: Errors, negative metrics, warnings
Yellow: Warnings, caution
Purple: Premium features, special content
Gray: Neutral content, disabled states

3. Metric Cards

Always include a descriptive label
Use appropriate trend indicators (+/- percentages)
Choose colors that match the sentiment (green for positive, red for negative)

4. Grid Layouts

Use 2-3 columns for optimal readability
Ensure consistent content types within grids
Consider mobile responsiveness

5. Content Hierarchy

Use headers to establish clear information hierarchy
Group related content with cards
Use separators to create visual breaks

Security Considerations

The dynamic-ui component operates in a sandboxed environment with the following restrictions:

No Code Execution: Only predefined component types are allowed
Content Sanitization: All text content is automatically sanitized
Limited Nesting: Components have reasonable depth limits
Data Validation: All section configurations are validated against schema

Error Handling

If invalid sections are provided, the component will:

Display an error message for the problematic section
Continue rendering valid sections
Log errors to the console for debugging

Example error display:

Error: Unknown section type: invalid-component

Tips for AI Models

Start Simple: Begin with basic layouts and add complexity gradually
Use Real Data: When possible, use actual data values instead of placeholders
Consider Context: Choose appropriate layouts and components for the user’s request
Test Incrementally: Build components step by step to avoid complex debugging
Follow Conventions: Use consistent naming and color schemes throughout the UI

Supported JSON Structure

All sections must be valid JSON. Here’s the TypeScript interface for reference:

interface UISection {
  type: 'header' | 'text' | 'metric' | 'chart' | 'button' | 'card' | 'grid' | 'list' | 'progress' | 'alert' | 'separator' | 'badge-group';
  id?: string;
  title?: string;
  text?: string;
  content?: string;
  value?: string | number;
  label?: string;
  trend?: string;
  color?: 'blue' | 'green' | 'red' | 'yellow' | 'purple' | 'gray' | 'orange';
  size?: 'small' | 'medium' | 'large';
  variant?: 'default' | 'secondary' | 'destructive' | 'outline';
  items?: UISection[];
  data?: any[];
  columns?: number;
  percentage?: number;
  alertType?: 'info' | 'warning' | 'error' | 'success';
  badges?: { text: string; color?: string }[];
}

This template-based approach ensures security while providing maximum flexibility for creating rich, interactive user interfaces.

Dynamic UI Component Usage Guide

🆕 NEW FEATURES: Interactive Forms & Functional Charts

Interactive Forms with Data Capture

Functional Charts with Real Data

Overview

Basic Syntax

Component Properties

Main Properties

Layout Types

Dashboard Layout

Form Layout

Card Layout

Section Types Reference

1. Header

2. Text

3. Metric Cards

4. Charts (Enhanced with Real Data)

5. Form Inputs

5a. Text Input

5b. Textarea

5c. Select Dropdown

5d. Checkbox

5e. Submit Button

6. Buttons

7. Cards

8. Grid Layout

9. Lists

10. Progress Bars

11. Alerts

12. Separators

13. Badge Groups

Complete Examples

Example 1: Sales Dashboard

Example 2: User Profile Form

Example 3: Project Status Report

Best Practices

1. Layout Selection

2. Color Usage

3. Metric Cards

4. Grid Layouts

5. Content Hierarchy

Security Considerations

Error Handling

Tips for AI Models

Supported JSON Structure