Components

Complete reference of all available HTML-like component tags that AI can use.

Overview

Melony provides a rich set of built-in components that AI can use with HTML-like syntax. All components support common props and can be nested to create complex UIs.

Layout Components

Card

Container component with optional title and padding.

<card title="Weather">
  <text value="Sunny, 72°F" />
</card>

<card title="Settings" padding="lg">
  <text value="Configure your preferences" />
</card>

Props:

• title - Optional card title

• padding - Size: xs, sm, md, lg, xl

Row

Horizontal layout container.

<row gap="md" align="center">
  <text value="Price:" />
  <text value="$99" weight="bold" />
  <badge label="Sale" variant="success" />
</row>

Props:

• gap - Spacing: xs, sm, md, lg, xl

• align - Alignment: start, center, end

• justify - Justify: start, center, end, between

Column

Vertical layout container.

<column gap="sm">
  <text value="Name" size="sm" color="muted" />
  <text value="John Doe" weight="bold" />
</column>

Props:

• gap - Spacing: xs, sm, md, lg, xl

• align - Alignment: start, center, end, stretch

Content Components

Text

Display text with various styling options.

<text value="Hello World" />
<text value="Large text" size="xl" weight="bold" />
<text value="Muted text" color="muted" />
<text value="Flexible" flex="1" />

Props:

• value - Text content (required)

• size - Font size: xs, sm, md, lg, xl

• weight - Font weight: normal, medium, semibold, bold

• color - Text color: primary, secondary, muted, success, warning, danger

• flex - Flex grow: "1" to fill space

Badge

Small label component for status indicators.

<badge label="New" />
<badge label="Success" variant="success" />
<badge label="Warning" variant="warning" />
<badge label="Error" variant="danger" />

Props:

• label - Badge text (required)

• variant - Style: primary, secondary, success, warning, danger, muted

Button

Interactive button with action support.

<button label="Click Me" />
<button label="Submit" variant="primary" />
<button label="Delete" variant="destructive" />
<button 
  label="Refresh" 
  variant="outline"
  action='{"type":"refresh","id":"123"}' 
/>

Props:

• label - Button text (required)

• variant - Style: primary, secondary, outline, destructive

• action - JSON action string (optional)

Link

Hyperlink component.

<link href="https://example.com" label="Visit Site" />
<link href="/about" label="Learn More" />

Props:

• href - URL (required)

• label - Link text (required)

Data Visualization

Chart

Display data in various chart formats.

<chart 
  type="line" 
  data='[{"month":"Jan","value":65},{"month":"Feb","value":72}]'
  xKey="month"
  yKey="value"
/>

<chart 
  type="bar" 
  data='[{"name":"Product A","sales":120},{"name":"Product B","sales":98}]'
  xKey="name"
  yKey="sales"
  title="Sales by Product"
/>

Props:

• type - Chart type: line, bar, area, pie

• data - JSON array of data points (required)

• xKey - X-axis data key (required for line/bar/area)

• yKey - Y-axis data key (required for line/bar/area)

• title - Chart title (optional)

Control Flow

For

Loop over arrays to render repeated content.

<for items='[{"name":"Alice"},{"name":"Bob"},{"name":"Charlie"}]'>
  <text value="{{item.name}}" />
</for>

<for items='[{"id":1,"task":"Buy milk"},{"id":2,"task":"Walk dog"}]'>
  <row gap="md">
    <text value="{{index + 1}}" />
    <text value="{{item.task}}" flex="1" />
  </row>
</for>

Props:

• items - JSON array (required)

Available Variables:

• {{item}} - Current item

• {{index}} - Current index (0-based)

• {{isFirst}}, {{isLast}}, {{isEven}}, {{isOdd}}

Advanced Components

Widget

Use custom widget templates.

<widget 
  type="weather" 
  location="San Francisco" 
  temperature="68" 
  condition="Sunny" 
/>

Props:

• type - Widget type identifier (required)

• Additional props depend on the widget template definition

Complete Example

Here's a comprehensive example using multiple components:

<card title="Sales Dashboard" padding="lg">
  <row gap="lg" align="stretch">
    <column gap="sm" flex="1">
      <text value="Total Revenue" size="sm" color="muted" />
      <text value="$124,500" size="xl" weight="bold" />
      <badge label="+12% this month" variant="success" />
    </column>
    
    <column gap="sm" flex="1">
      <text value="Active Users" size="sm" color="muted" />
      <text value="1,234" size="xl" weight="bold" />
      <badge label="+5% this week" variant="success" />
    </column>
  </row>

  <chart 
    type="line"
    data='[
      {"month":"Jan","revenue":45000},
      {"month":"Feb","revenue":52000},
      {"month":"Mar","revenue":48000}
    ]'
    xKey="month"
    yKey="revenue"
    title="Monthly Revenue"
  />

  <card title="Top Products">
    <for items='[
      {"name":"Product A","sales":120,"trend":"up"},
      {"name":"Product B","sales":98,"trend":"down"},
      {"name":"Product C","sales":145,"trend":"up"}
    ]'>
      <row gap="md" align="center">
        <text value="{{item.name}}" flex="1" />
        <text value="{{item.sales}} sales" weight="medium" />
        <badge 
          label="{{item.trend === 'up' ? '↑' : '↓'}}" 
          variant="{{item.trend === 'up' ? 'success' : 'danger'}}" 
        />
      </row>
    </for>
  </card>

  <row gap="sm">
    <button label="Export Data" variant="primary" />
    <button label="Refresh" variant="outline" action='{"type":"refresh"}' />
  </row>
</card>

Best Practices

  • Use semantic component names that reflect their purpose
  • Keep nesting levels reasonable (3-4 levels max)
  • Use layout components (row, column) for consistent spacing
  • Leverage variants for different visual styles
  • Combine components to create rich, interactive UIs
  • Use the flex prop for responsive layouts

Next Steps

Actions & Events - Learn how to handle button clicks and user interactions

Theming - Customize component appearance

Control Flow - Master the <for> component