Define Custom Tools Without a Global Registry in React

You don’t need to register custom connectors anywhere. Any object that satisfies the Tool type works directly with ToolCard. There is no global registry, provider, or configuration step — define a plain object that matches the type and pass it straight to the component.

Minimal custom tool

The only required fields are id and name. Everything else is optional:

import { ToolCard, type Tool } from "ai-tool-elements";
import "ai-tool-elements/styles.css";

const MyConnector: Tool = {
  id: "my-connector",
  name: "My Connector",
};

export function MyConnectorCard() {
  return <ToolCard tool={MyConnector} />;
}

Custom tool with fields and an inline SVG image

Use as const satisfies Tool for the strictest typing, an inline SVG string for the logo, and a fields array to describe the connector’s configuration inputs:

import { ToolCard, type Tool } from "ai-tool-elements";
import "ai-tool-elements/styles.css";

const acmeLogo = String.raw`
  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
    <circle cx="12" cy="12" r="10" fill="#6D5EF7"/>
    <path d="M7 16 12 6l5 10h-3l-2-4-2 4H7Z" fill="#fff"/>
  </svg>
`;

const Acme = {
  id: "acme",
  name: "Acme",
  description: "A project-defined connector.",
  image: { type: "svg", content: acmeLogo },
  fields: [
    {
      name: "apiKey",
      label: "API key",
      description: "Secret used to authenticate requests.",
      required: true,
    },
  ],
} as const satisfies Tool;

export function AcmeCard() {
  return <ToolCard tool={Acme} />;
}

SVG content must be the complete <svg>...</svg> markup including a viewBox. Use explicit fill colors — an SVG rendered via <img> does not inherit CSS currentColor. Only include SVG markup you fully trust.

Custom tool with a hosted image URL

If you have a stable hosted asset, use { type: "url", src: "..." } instead of an inline SVG string:

import { type Tool } from "ai-tool-elements";

const AcmeHosted: Tool = {
  id: "acme-hosted",
  name: "Acme",
  image: { type: "url", src: "https://example.com/acme-logo.svg" },
};

Type-safe custom tools

For the strictest compile-time guarantees, use as const satisfies Tool. TypeScript will narrow every field to its literal type, and fields will be typed as a readonly tuple:

import { type Tool } from "ai-tool-elements";

const Weather = {
  id: "weather",
  name: "Weather API",
  description: "Current and forecast weather data.",
  fields: [
    { name: "apiKey", label: "API Key", required: true },
    { name: "units", label: "Units", description: "metric or imperial", required: false },
  ],
} as const satisfies Tool;

// Weather.fields is readonly and fully typed

Mixing catalog and custom tools

Catalog entries and custom tools share the same Tool type, so they can be combined freely in a single array:

import { Slack, type Tool, ToolCard, toolCatalog } from "ai-tool-elements";
import "ai-tool-elements/styles.css";

const InternalCRM: Tool = { id: "internal-crm", name: "Internal CRM" };

const myAgentTools: readonly Tool[] = [
  Slack,
  toolCatalog.find((t) => t.id === "gmail")!,
  InternalCRM,
];

export function AgentToolList() {
  return myAgentTools.map((tool) => <ToolCard key={tool.id} tool={tool} />);
}

Get Started

Components

Tool Catalog

Guides

Define Custom Tools Without a Global Registry in React

Minimal custom tool

Custom tool with fields and an inline SVG image

Custom tool with a hosted image URL

Type-safe custom tools

Mixing catalog and custom tools

​Minimal custom tool

​Custom tool with fields and an inline SVG image

​Custom tool with a hosted image URL

​Type-safe custom tools

​Mixing catalog and custom tools

Minimal custom tool

Custom tool with fields and an inline SVG image

Custom tool with a hosted image URL

Type-safe custom tools

Mixing catalog and custom tools