ai-elements-nuxt

Nuxt/Vue complement to Vercel AI Elements — headless AI UI components for the AI SDK ecosystem.

Documentation · npm · Contributing · Code of Conduct · Security · Changelog

Not a replacement for AI Elements. This project extends the same UI patterns to Nuxt 3 and Vue 3 so you can build AI-native apps with your own design system.

Install

1. Core (always required):

pnpm add ai-elements-nuxt ai @ai-sdk/vue

2. Choose a model provider (at least one required for production):

pnpm add @ai-sdk/openai        # OpenAI / GPT-4o
# pnpm add @ai-sdk/anthropic   # Anthropic / Claude
# pnpm add @ai-sdk/google      # Google / Gemini
# pnpm add @ai-sdk/mistral     # Mistral

Full provider list → ai-sdk.dev/providers

3. Agents only — add Zod for tool parameter schemas:

pnpm add zod

Set your API key in .env (Nuxt reads it automatically):

OPENAI_API_KEY=sk-...

Register the module:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['ai-elements-nuxt'],
  aiElements: {
    defaultStyles: true, // optional base CSS for [data-ai-*] attributes
  },
})

What do you need?

Goal	Key components	Composable	Server handler
Streaming chat	AiMessage, AiPromptInput	useAiChat	createChatHandler
Agent with tools	+ AiAgent, AiTool, AiToolApproval	useAiAgent, useAiTools	createAgentHandler
Persisted chat	same as chat	useAiChatPersisted	same as chat
Realtime voice	AiRealtimeChat	useAiRealtime	—

Install from GitHub

To use the latest commit from the repository instead of the npm release:

pnpm add github:albegosu/ai-elements-nuxt

With pnpm strict build settings, allow the module to run its prepack build:

# pnpm-workspace.yaml (consumer monorepo root)
allowBuilds:
  ai-elements-nuxt: true

Types in consumer apps:

import type { AiMessageProps, AiSource } from 'ai-elements-nuxt/types'

Quick start (streaming chat)

1. Server route (server/api/chat.post.ts):

// Start with mock (no API key needed):
import { createMockChatHandler } from 'ai-elements-nuxt/server'
export default createMockChatHandler()

// Swap for production:
// import { createChatHandler } from 'ai-elements-nuxt/server'
// import { openai } from '@ai-sdk/openai'
// export default createChatHandler({ model: openai('gpt-4o') })

2. Page:

<script setup lang="ts">
const { aiMessages, input, handleSubmit, isStreaming } = useAiChat({ api: '/api/chat' })
</script>

<template>
  <AiMessage v-for="(msg, i) in aiMessages" :key="i" v-bind="msg">
    <template #content="{ content, isStreaming: streaming }">
      <AiStreamingCursor v-if="streaming && content" :active="true" />
      {{ content }}
    </template>
  </AiMessage>
  <form @submit="handleSubmit">
    <AiPromptInput v-model="input" :loading="isStreaming" />
  </form>
</template>

Agentic apps

Server — multi-step tools with optional human approval:

import { createAgentHandler } from 'ai-elements-nuxt/server'
import { openai } from '@ai-sdk/openai'
import { z } from 'zod'

export default createAgentHandler({
  model: openai('gpt-4o'),
  maxSteps: 10,
  tools: {
    getWeather: {
      description: 'Get weather for a city',
      parameters: z.object({ city: z.string() }),
      execute: async ({ city }) => ({ temp: 72, city }),
    },
    deleteFile: {
      description: 'Delete a file',
      parameters: z.object({ path: z.string() }),
      requireConfirmation: true,
      execute: async ({ path }) => ({ deleted: path }),
    },
  },
})

Client — useAiAgent + useAiTools:

<script setup lang="ts">
const agent = useAiAgent({ api: '/api/chat' })
// useAiTools wires per-tool metadata; pendingApprovals is already AiToolCall[] — no reshaping needed
const tools = useAiTools([
  { name: 'getWeather' },
  { name: 'deleteFile', requireConfirmation: true },
], agent)
const { aiMessages, steps, handleSubmit, input } = agent
</script>

<template>
  <!-- AiAgent (also AiAgentSteps) renders the steps[] from useAiAgent -->
  <AiAgent :steps="steps" title="Agent run" />

  <!-- pendingApprovals[0] is already AiToolCall-shaped — pass directly -->
  <AiToolApproval
    v-if="tools.pendingApprovals.value[0]"
    :tool-call="tools.pendingApprovals.value[0]"
    @approve="tools.approveTool"
    @deny="tools.denyTool"
  />

  <AiMessage v-for="(msg, i) in aiMessages" :key="i" v-bind="msg" />
  <form @submit="handleSubmit">
    <AiPromptInput v-model="input" />
  </form>
</template>

See AGENTS.md for step-by-step recipes for coding agents.

Markdown rendering

<script setup lang="ts">
const { html } = useAiMarkdown(() => markdownSource)
</script>

<template>
  <AiMarkdown :content="markdownSource" />
  <!-- or -->
  <div v-html="html" />
</template>

GFM (tables, task lists, strikethrough) is enabled by default via marked. Use auto-imported simpleParse for a lightweight fallback (no tables — useful during streaming to avoid layout shifts):

const { html } = useAiMarkdown(() => markdownSource, { parse: simpleParse })

Components (66)

All components are auto-imported with the Ai prefix.

Category	Components
Chatbot	Message, PromptInput, Conversation (thread list / sidebar), Reasoning, ChainOfThought, Sources, Tool, ToolApproval, ApprovalPolicy, Suggestion, Attachments, Shimmer, StreamingCursor, Plan, Task, Checkpoint, Confirmation, Context, Queue, InlineCitation, ModelSelector, ErrorBoundary, ScreenshotButton, DownloadConversation, Branch, SpeechButton, SourceDocuments
Code	CodeBlock, Terminal, FileTree, StackTrace, Agent (also AiAgentSteps), AgentTimeline, Artifact, Commit, SchemaDisplay, PackageInfo, EnvVars, TestResults, Snippet, WebPreview, Sandbox, SandboxPreview, VuePreview
Voice	SpeechInput, Transcription, AudioPlayer, MicSelector, VoiceSelector, Persona, RealtimeChat
Workflow	Canvas, Node, Edge, Connection, Controls, Panel, Toolbar
Utilities	Image, OpenInChat, Markdown, JsxPreview, FileUpload, VideoPlayer, McpApp, RuntimeContext

Composables

Composable	Description
useAiChat	Wraps @ai-sdk/vue Chat when api is set; supports body / headers / credentials; local state without api
useAiChatLocal	Local message state without AI SDK
useAiChatPersisted	useAiChat with localStorage/sessionStorage persistence
useAiAgent	Agent steps, plan, tasks, and confirmation flow on top of chat
useAiTools	Declarative per-tool UI metadata wired to useAiAgent; exposes pendingApprovals (typed AiToolCall[]) for AiToolApproval
useAiRealtime	Vue composable wrapping AI SDK v7 AbstractRealtimeSession — connection, audio capture/playback, messages
useAiWorkflow	Workflow graph nodes/edges state
useAiCompletion	Wraps @ai-sdk/vue useCompletion
useAiMarkdown	Markdown string → sanitized HTML (GFM via marked); pass { parse: simpleParse } for lightweight fallback
useScreenshotCapture	Capture a screenshot via getDisplayMedia → { dataUrl, blob, file } for prompt attachments
useSpeechRecognition	Web Speech API wrapper (start/stop/toggle, transcript, interim, supported) — powers AiSpeechInput / AiSpeechButton
mapMessageParts / toAiMessageProps	Map AI SDK UIMessage.parts → AiMessage props

Server utilities

import {
  createChatHandler,
  createMockChatHandler,
  createAgentHandler,
} from 'ai-elements-nuxt/server'

For AI agents (MCP + skill)

The package ships tooling so coding agents can build with the library accurately:

• MCP server — a Model Context Protocol stdio server exposing the component registry:

  npx ai-elements-nuxt-mcp

  Tools: list_components, get_component, search_components, list_composables; resource ai-elements://registry. Add it to your MCP client (Claude Code / Cursor) as a stdio server running that command.

• Skill — skills/ai-elements-nuxt/SKILL.md, an installable agent skill with an auto-generated component list. Copy it into your agent's skills directory (e.g. .claude/skills/).

• Registry JSON — import the raw metadata directly: import registry from 'ai-elements-nuxt/registry'.

• AGENTS.md — full implementation guide (also drives .cursor/rules).

The component/composable lists in the skill and AGENTS.md are generated from registry/components.json, so they never drift from the code.

Development

git clone https://github.com/albegosu/ai-elements-nuxt.git
cd ai-elements-nuxt
pnpm install
pnpm dev

See .github/CONTRIBUTING.md for the full contributor guide (lint, test, docs conventions).

Documentation & playground

pnpm dev

Opens the docs site at http://localhost:3000 (or the hosted docs) with:

• Guides: getting started, building a chat, custom transport & RAG, building an agent, styling, composables
• Component reference with Preview/Code tabs for all 66 components
• Playgrounds: chat, streaming, agent, code, voice & workflow

Philosophy

• Headless: slot-driven, data-ai-* attributes, no forced design system
• Compatible: follows AI SDK UIMessage.parts contract
• Nuxt-native: module auto-imports, Nitro server helpers
• Agent-ready: AGENTS.md and .cursor/rules/ for AI coding tools

Credits

Inspired by and designed to complement vercel/ai-elements and the AI SDK.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md and our Code of Conduct before opening a pull request.

License

MIT