@taibin/a2ui-vue

🎨 A Vue renderer for A2UI v0.9 specification.

This project is a reference implementation following the React renderer. It uses web_core for core logic, Rslib for library builds, and Rsbuild for demo page builds.

📦 Setup

Install the dependencies:

pnpm install

🚀 Get started

Build the library:

pnpm run build

Run the demo in watch mode:

pnpm run dev

📖 Usage

Basic Setup

<script setup>
import { renderMarkdown } from '@a2ui/markdown-it';
import { basicCatalog, A2uiSurface, useSurfaces, provideMarkdownRenderer } from '@taibin/a2ui-vue';
import { shallowRef } from 'vue';
import '@fontsource/material-symbols-outlined';

// Provide markdown renderer if you need to render markdown content
provideMarkdownRenderer(renderMarkdown);

// Create a reactive ref to store A2UI messages
const agentMessages = shallowRef([]);

// Initialize surfaces with the basic catalog and messages
const surfaces = useSurfaces(basicCatalog, agentMessages);
</script>

<template>
  <A2uiSurface
    v-for="surface in surfaces"
    :key="surface.id"
    :surface="surface"
  />
</template>

Processing A2UI Messages

The library processes A2UI messages to render dynamic UI components. Messages can be streamed from an agent or backend service:

// Example: Add a message to create a surface
agentMessages.value = [
  ...agentMessages.value,
  {
    version: 'v0.9',
    createSurface: { surfaceId: 'main-chat', catalogId: basicCatalog.id },
  },
];

Streaming Rendering

This example demonstrates how to stream A2UI messages and render components dynamically:

<script setup>
import { renderMarkdown } from '@a2ui/markdown-it';
import {
  basicCatalog,
  A2uiSurface,
  useSurfaces,
  provideMarkdownRenderer,
} from '@taibin/a2ui-vue';
import { onMounted, onUnmounted, shallowRef } from 'vue';
import '@fontsource/material-symbols-outlined';

provideMarkdownRenderer(renderMarkdown);

// Create a reactive ref to store A2UI messages
const agentMessages = shallowRef([]);

// Initialize surfaces with the basic catalog and messages
const surfaces = useSurfaces(basicCatalog, agentMessages);

// Sample messages simulating streaming output from an agent
const sampleAgentMessages = [
  // 1. First, create surface
  {
    version: 'v0.9',
    createSurface: { surfaceId: 'main-chat', catalogId: basicCatalog.id },
  },
  // 2. Create root component Card
  {
    version: 'v0.9',
    updateComponents: {
      surfaceId: 'main-chat',
      components: [
        {
          id: 'root',
          component: 'Card',
          child: 'main-column',
        },
      ],
    },
  },
  // 3. Create main layout Column
  {
    version: 'v0.9',
    updateComponents: {
      surfaceId: 'main-chat',
      components: [
        {
          id: 'main-column',
          component: 'Column',
          children: [
            'header-row',
            'image',
            'greeting-text',
            'subtext',
            'divider',
            'button-row',
          ],
          align: 'center',
        },
      ],
    },
  },
  // 4. Create header-row
  {
    version: 'v0.9',
    updateComponents: {
      surfaceId: 'main-chat',
      components: [
        {
          id: 'header-row',
          component: 'Row',
          children: ['icon', 'header-text'],
          align: 'center',
          justify: 'center',
        },
      ],
    },
  },
  // 5. Create icon and header-text
  {
    version: 'v0.9',
    updateComponents: {
      surfaceId: 'main-chat',
      components: [
        {
          id: 'icon',
          component: 'Icon',
          name: 'favorite',
        },
        {
          id: 'header-text',
          component: 'Text',
          text: 'Welcome Message',
          variant: 'h3',
        },
      ],
    },
  },
  // 6. Create image
  {
    version: 'v0.9',
    updateComponents: {
      surfaceId: 'main-chat',
      components: [
        {
          id: 'image',
          component: 'Image',
          url: 'https://images.unsplash.com/photo-1506744038136-46273834b3fb?auto=format&fit=crop&w=600&q=80',
          fit: 'cover',
          variant: 'mediumFeature',
        },
      ],
    },
  },
  // 7. Create greeting-text
  {
    version: 'v0.9',
    updateComponents: {
      surfaceId: 'main-chat',
      components: [
        {
          id: 'greeting-text',
          component: 'Text',
          text: 'Hello, welcome to A2UI!',
          variant: 'h2',
        },
      ],
    },
  },
  // 8. Create subtext
  {
    version: 'v0.9',
    updateComponents: {
      surfaceId: 'main-chat',
      components: [
        {
          id: 'subtext',
          component: 'Text',
          text: 'This stylish greeting card includes an image, icon, and a button with an action.',
          variant: 'body',
        },
      ],
    },
  },
  // 9. Create divider
  {
    version: 'v0.9',
    updateComponents: {
      surfaceId: 'main-chat',
      components: [
        {
          id: 'divider',
          component: 'Divider',
          axis: 'horizontal',
        },
      ],
    },
  },
  // 10. Create button-row
  {
    version: 'v0.9',
    updateComponents: {
      surfaceId: 'main-chat',
      components: [
        {
          id: 'button-row',
          component: 'Row',
          children: ['ok-button'],
          justify: 'center',
        },
      ],
    },
  },
  // 11. Create button text and button
  {
    version: 'v0.9',
    updateComponents: {
      surfaceId: 'main-chat',
      components: [
        {
          id: 'ok-button-text',
          component: 'Text',
          text: 'OK',
        },
        {
          id: 'ok-button',
          component: 'Button',
          child: 'ok-button-text',
          action: {
            event: {
              name: 'okClicked',
            },
          },
        },
      ],
    },
  },
];

// Simulate streaming output: append each message every second
let messageIndex = 0;
let streamTimer = null;

const startStreamSimulation = () => {
  if (streamTimer) return;

  streamTimer = setInterval(() => {
    if (messageIndex >= sampleAgentMessages.length) {
      if (streamTimer) {
        clearInterval(streamTimer);
        streamTimer = null;
      }
      return;
    }

    // Append new message to array
    agentMessages.value = [
      ...agentMessages.value,
      sampleAgentMessages[messageIndex],
    ];
    messageIndex++;
  }, 1000);
};

onMounted(() => {
  startStreamSimulation();
});

onUnmounted(() => {
  if (streamTimer) {
    clearInterval(streamTimer);
    streamTimer = null;
  }
});
</script>

<template>
  <div className="a2ui-container">
    <div v-if="!surfaces.length">Waiting for agent...</div>
    <A2uiSurface
      v-for="surface in surfaces"
      :key="surface.id"
      :surface="surface"
    />
  </div>
</template>

🪝 Composables

useSurfaces

The useSurfaces composable manages the lifecycle of A2UI surfaces and processes messages:

<script setup>
import { basicCatalog, useSurfaces } from '@taibin/a2ui-vue';
import { shallowRef } from 'vue';

// Create a reactive ref for messages
const agentMessages = shallowRef([]);

// Initialize surfaces - this will process messages and manage surface lifecycle
const surfaces = useSurfaces(basicCatalog, agentMessages);

// Surfaces is a reactive ref containing an array of active surfaces
// It updates automatically when surfaces are created or deleted
</script>

useA2uiNode

💡 This composable is forked from meldui/a2ui. Thanks! ❤

The useA2uiNode composable resolves a single component node within a surface and keeps it reactive:

<script setup>
import { useA2uiNode } from '@taibin/a2ui-vue';
import { computed } from 'vue';

// Props required by useA2uiNode
const props = defineProps({
  surface: { type: Object, required: true },
  id: { type: String, required: true },
  basePath: String,
});

// Destructure the returned values
const {
  status,
  type,
  api,
  props: nodeProps,
  context,
} = useA2uiNode(props.surface, props.id, props.basePath);
</script>

<template>
  <div>
    <div v-if="status === 'loading'">Loading...</div>
    <div v-else-if="status === 'unknown'">Unknown component type</div>
    <div v-else>
      <!-- Render component with bound props -->
      <MyComponent v-bind="nodeProps" />
    </div>
  </div>
</template>

useA2uiNode Return Values

| Property | Type | Description | |----------|------|-------------| | status | ComputedRef<'loading' \| 'unknown' \| 'ready'> | Current node status | | type | ComputedRef<string \| undefined> | Component type name | | api | ComputedRef<ComponentApi \| undefined> | Resolved component API | | props | ShallowRef<Record<string, unknown>> | Reactive resolved props | | context | ShallowRef<ComponentContext \| undefined> | Component context |

🧩 Available Components

The basic catalog includes the following components:

| Component | Description | |-----------|-------------| | Text | Display text content | | Image | Display images | | Icon | Display icons | | Video | Display video content | | AudioPlayer | Play audio | | Row | Horizontal layout | | Column | Vertical layout | | List | List container | | Card | Card container | | Tabs | Tab navigation | | Divider | Visual separator | | Modal | Modal dialog | | Button | Clickable button | | TextField | Text input field | | CheckBox | Checkbox input | | ChoicePicker | Selection picker | | Slider | Range slider | | DateTimeInput | Date and time picker |

⚠️ Maintenance Notice

This project is developed in spare time with AI assistance. There is limited capacity for ongoing maintenance. You are welcome to fork, modify, and use this project in accordance with the license agreement.

📄 License

The package is automatically published under the Apache-2.0 open-source license, as defined in package.json.