Skip to content

components.md

Latest commit

 

History

History
650 lines (487 loc) · 12.5 KB

components.md

File metadata and controls

650 lines (487 loc) · 12.5 KB

Component Gallery

This page showcases all A2UI components with examples and usage patterns.

!!! abstract "Schema Files"

=== "v0.8"

    [:material-code-json: Standard Catalog Definition (JSON Schema)](https://a2ui.org/specification/v0_8/standard_catalog_definition.json)

=== "v0.9"

    [:material-code-json: Basic Catalog Definition (JSON Schema)](https://a2ui.org/specification/v0_9/basic_catalog.json)

Layout Components

Row

Horizontal layout container. Children are arranged left-to-right.

=== "v0.8"

**Properties:** `children` (`explicitList` or `template`), `distribution`, `alignment`

```json
{
  "id": "toolbar",
  "component": {
    "Row": {
      "children": { "explicitList": ["btn1", "btn2", "btn3"] },
      "distribution": "spaceBetween",
      "alignment": "center"
    }
  }
}
```

=== "v0.9"

**Properties:** `children` (array or template), `justify`, `align`

```json
{
  "id": "toolbar",
  "component": "Row",
  "children": ["btn1", "btn2", "btn3"],
  "justify": "spaceBetween",
  "align": "center"
}
```

Column

Vertical layout container. Children are arranged top-to-bottom.

=== "v0.8"

**Properties:** `children` (`explicitList` or `template`), `distribution`, `alignment`

```json
{
  "id": "content",
  "component": {
    "Column": {
      "children": { "explicitList": ["header", "body", "footer"] },
      "distribution": "start",
      "alignment": "stretch"
    }
  }
}
```

=== "v0.9"

**Properties:** `children` (array or template), `justify`, `align`

```json
{
  "id": "content",
  "component": "Column",
  "children": ["header", "body", "footer"],
  "justify": "start",
  "align": "stretch"
}
```

List

Scrollable list of items. Supports static children and dynamic templates.

=== "v0.8"

**Properties:** `children` (`explicitList` or `template`), `direction`, `alignment`

```json
{
  "id": "message-list",
  "component": {
    "List": {
      "children": {
        "template": {
          "dataBinding": "/messages",
          "componentId": "message-item"
        }
      },
      "direction": "vertical"
    }
  }
}
```

=== "v0.9"

**Properties:** `children` (array or template), `direction`, `align`

```json
{
  "id": "message-list",
  "component": "List",
  "children": {
    "componentId": "message-item",
    "path": "/messages"
  },
  "direction": "vertical"
}
```

Display Components

Text

Display text content with styling hints.

=== "v0.8"

**Properties:** `text` (BoundValue), `usageHint`

`usageHint` values: `h1`, `h2`, `h3`, `h4`, `h5`, `caption`, `body`

```json
{
  "id": "title",
  "component": {
    "Text": {
      "text": { "literalString": "Welcome to A2UI" },
      "usageHint": "h1"
    }
  }
}
```

=== "v0.9"

**Properties:** `text` (string or DataBinding), `variant`

`variant` values: `h1`, `h2`, `h3`, `h4`, `h5`, `caption`, `body`

```json
{
  "id": "title",
  "component": "Text",
  "text": "Welcome to A2UI",
  "variant": "h1"
}
```

Image

Display images from URLs.

=== "v0.8"

**Properties:** `url` (BoundValue), `fit`, `usageHint`

```json
{
  "id": "hero",
  "component": {
    "Image": {
      "url": { "literalString": "https://example.com/hero.png" },
      "fit": "cover",
      "usageHint": "hero"
    }
  }
}
```

=== "v0.9"

**Properties:** `url` (string or DataBinding), `fit`, `variant`

```json
{
  "id": "hero",
  "component": "Image",
  "url": "https://example.com/hero.png",
  "fit": "cover",
  "variant": "hero"
}
```

Icon

Display icons from the standard set defined in the catalog.

=== "v0.8"

**Properties:** `name` (BoundValue)

```json
{
  "id": "check-icon",
  "component": {
    "Icon": {
      "name": { "literalString": "check" }
    }
  }
}
```

=== "v0.9"

**Properties:** `name` (string or DataBinding)

```json
{
  "id": "check-icon",
  "component": "Icon",
  "name": "check"
}
```

Divider

Visual separator line.

=== "v0.8"

**Properties:** `axis`

```json
{
  "id": "separator",
  "component": {
    "Divider": {
      "axis": "horizontal"
    }
  }
}
```

=== "v0.9"

**Properties:** `axis`

```json
{
  "id": "separator",
  "component": "Divider",
  "axis": "horizontal"
}
```

Interactive Components

Button

Clickable button that triggers an action.

=== "v0.8"

**Properties:** `child` (component ID), `primary` (boolean), `action`

```json
{
  "id": "submit-btn",
  "component": {
    "Button": {
      "child": "submit-text",
      "primary": true,
      "action": {
        "name": "submit_form"
      }
    }
  }
}
```

=== "v0.9"

**Properties:** `child` (component ID), `variant`, `action`

```json
{
  "id": "submit-btn",
  "component": "Button",
  "child": "submit-text",
  "variant": "primary",
  "action": {
    "event": {
      "name": "submit_form"
    }
  }
}
```

TextField

Text input field with optional validation.

=== "v0.8"

**Properties:** `label` (BoundValue), `text` (BoundValue), `textFieldType`, `validationRegexp`

`textFieldType` values: `shortText`, `longText`, `number`, `obscured`, `date`

```json
{
  "id": "email-input",
  "component": {
    "TextField": {
      "label": { "literalString": "Email Address" },
      "text": { "path": "/user/email" },
      "textFieldType": "shortText"
    }
  }
}
```

=== "v0.9"

**Properties:** `label` (string), `value` (string or DataBinding), `textFieldType`, `validationRegexp`

`textFieldType` values: `shortText`, `longText`, `number`, `obscured`, `date`

```json
{
  "id": "email-input",
  "component": "TextField",
  "label": "Email Address",
  "value": { "path": "/user/email" },
  "textFieldType": "shortText"
}
```

CheckBox

Boolean toggle.

=== "v0.8"

**Properties:** `label` (BoundValue), `value` (BoundValue, boolean)

```json
{
  "id": "terms-checkbox",
  "component": {
    "CheckBox": {
      "label": { "literalString": "I agree to the terms" },
      "value": { "path": "/form/agreedToTerms" }
    }
  }
}
```

=== "v0.9"

**Properties:** `label` (string), `value` (DataBinding, boolean)

```json
{
  "id": "terms-checkbox",
  "component": "CheckBox",
  "label": "I agree to the terms",
  "value": { "path": "/form/agreedToTerms" }
}
```

Slider

Numeric range input.

=== "v0.8"

**Properties:** `value` (BoundValue), `minValue`, `maxValue`

```json
{
  "id": "volume",
  "component": {
    "Slider": {
      "value": { "path": "/settings/volume" },
      "minValue": 0,
      "maxValue": 100
    }
  }
}
```

=== "v0.9"

**Properties:** `value` (DataBinding), `minValue`, `maxValue`

```json
{
  "id": "volume",
  "component": "Slider",
  "value": { "path": "/settings/volume" },
  "minValue": 0,
  "maxValue": 100
}
```

DateTimeInput

Date and/or time picker.

=== "v0.8"

**Properties:** `value` (BoundValue), `enableDate`, `enableTime`

```json
{
  "id": "date-picker",
  "component": {
    "DateTimeInput": {
      "value": { "path": "/booking/date" },
      "enableDate": true,
      "enableTime": false
    }
  }
}
```

=== "v0.9"

**Properties:** `value` (DataBinding), `enableDate`, `enableTime`

```json
{
  "id": "date-picker",
  "component": "DateTimeInput",
  "value": { "path": "/booking/date" },
  "enableDate": true,
  "enableTime": false
}
```

MultipleChoice (v0.8) / ChoicePicker (v0.9)

Select one or more options from a list.

=== "v0.8"

**Properties:** `options` (array), `selections` (BoundValue), `maxAllowedSelections`

```json
{
  "id": "country-select",
  "component": {
    "MultipleChoice": {
      "options": [
        { "label": { "literalString": "USA" }, "value": "us" },
        { "label": { "literalString": "Canada" }, "value": "ca" }
      ],
      "selections": { "path": "/form/country" },
      "maxAllowedSelections": 1
    }
  }
}
```

=== "v0.9"

**Properties:** `options` (array), `selections` (DataBinding), `maxAllowedSelections`

```json
{
  "id": "country-select",
  "component": "ChoicePicker",
  "options": [
    { "label": "USA", "value": "us" },
    { "label": "Canada", "value": "ca" }
  ],
  "selections": { "path": "/form/country" },
  "maxAllowedSelections": 1
}
```

Container Components

Card

Container with elevation/border and padding.

=== "v0.8"

**Properties:** `child` (component ID)

```json
{
  "id": "info-card",
  "component": {
    "Card": {
      "child": "card-content"
    }
  }
}
```

=== "v0.9"

**Properties:** `child` (component ID)

```json
{
  "id": "info-card",
  "component": "Card",
  "child": "card-content"
}
```

Modal

Overlay dialog triggered by an entry point component.

=== "v0.8"

**Properties:** `entryPointChild` (component ID), `contentChild` (component ID)

```json
{
  "id": "confirmation-modal",
  "component": {
    "Modal": {
      "entryPointChild": "open-modal-btn",
      "contentChild": "modal-content"
    }
  }
}
```

=== "v0.9"

**Properties:** `entryPointChild` (component ID), `contentChild` (component ID)

```json
{
  "id": "confirmation-modal",
  "component": "Modal",
  "entryPointChild": "open-modal-btn",
  "contentChild": "modal-content"
}
```

Tabs

Tabbed interface for organizing content into switchable panels.

=== "v0.8"

**Properties:** `tabItems` (array of `{ title, child }`)

```json
{
  "id": "settings-tabs",
  "component": {
    "Tabs": {
      "tabItems": [
        { "title": { "literalString": "General" }, "child": "general-tab" },
        { "title": { "literalString": "Privacy" }, "child": "privacy-tab" }
      ]
    }
  }
}
```

=== "v0.9"

**Properties:** `tabItems` (array of `{ title, child }`)

```json
{
  "id": "settings-tabs",
  "component": "Tabs",
  "tabItems": [
    { "title": "General", "child": "general-tab" },
    { "title": "Privacy", "child": "privacy-tab" }
  ]
}
```

Common Properties

All components share:

  • id (required): Unique identifier within the surface
  • accessibility: Accessibility attributes (label, role)
  • weight: Flex-grow value when inside a Row or Column

Version Differences Summary

The component names and properties are largely the same across versions. The structural differences are:

Aspect v0.8 v0.9
Component wrapper "component": { "Text": { ... } } "component": "Text", ...props
String values { "literalString": "Hello" } "Hello"
Children { "explicitList": ["a", "b"] } ["a", "b"]
Data binding { "path": "/data" } { "path": "/data" } (same)
Text/Image styling usageHint variant
Button styling primary: true variant: "primary"
Action format { "name": "..." } { "event": { "name": "..." } }
Choice component MultipleChoice ChoicePicker
Layout alignment distribution, alignment justify, align
TextField value text value

Live Examples

To see all components in action:

cd samples/client/angular
npm start -- gallery

Further Reading

!!! abstract "Schema Files"

=== "v0.8"

    [:material-code-json: Standard Catalog Definition (JSON Schema)](https://a2ui.org/specification/v0_8/standard_catalog_definition.json)

=== "v0.9"

    [:material-code-json: Basic Catalog Definition (JSON Schema)](https://a2ui.org/specification/v0_9/basic_catalog.json)