Complete TypeScript Type Reference for ai-tool-elements

ai-tool-elements ships TypeScript declarations alongside its JavaScript output. All public types are re-exported from the main entry point (ai-tool-elements) — no separate @types/ package is needed. Consuming the library in a TypeScript project gives you full type safety on tool definitions, card props, and catalog entries.

Exported types

The following types are declared in src/types.ts and re-exported from the package root.

`ToolField`

A single configuration field on a tool, rendered as a row inside the card’s content area.

// A single field on a tool's configuration form
export type ToolField = Readonly<{
  name: string;         // Unique field identifier (e.g. "apiKey")
  label?: string;       // Display label (falls back to name)
  description?: string; // Help text shown below the label
  required?: boolean;   // Shown as "Required" or "Optional"
}>;

`ToolImage`

The logo for a tool — either inline SVG markup or a hosted URL. The card renders images through a standard <img> element, so SVG content must be complete and self-contained.

// A tool's logo, either inline SVG or a hosted URL
export type ToolImage =
  | Readonly<{ type: "svg"; content: string }>
  | Readonly<{ type: "url"; src: string }>;

`Tool`

The core connector definition. Every catalog entry and application-defined connector satisfies this shape.

// A tool/connector definition
export type Tool = Readonly<{
  id: string;           // Stable unique slug (e.g. "slack")
  name: string;         // Display name (e.g. "Slack")
  description?: string;
  image?: ToolImage;
  fields?: readonly ToolField[];
}>;

`ToolCatalogItem`

An alias for Tool. Used to annotate entries in the built-in catalog — semantically it signals that the object is part of the published catalog rather than a one-off application definition.

// Alias for Tool — used for catalog entries
export type ToolCatalogItem = Tool;

Using the Tool type

Define custom connectors with as const satisfies Tool to get the narrowest possible literal types while still being checked against the Tool shape. TypeScript will then enforce that all required fields are present and that extra fields do not violate the readonly constraint.

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

const MyAPI = {
  id: "my-api",
  name: "My API",
  description: "Internal data API.",
  fields: [
    { name: "endpoint", label: "Endpoint URL", required: true },
    { name: "token", label: "Bearer Token", required: true },
  ],
} as const satisfies Tool;

// MyAPI.fields is readonly ToolField[] — TypeScript enforces the shape

as const makes every string literal and nested property a narrow readonly type. satisfies Tool validates the shape at the point of definition without widening the type to Tool, so later code still benefits from the exact literal types.

ToolCard generics

ToolCard is generic over any subtype of Tool. If you define a connector type that adds fields beyond the base Tool shape, those extra properties remain accessible through the tool prop inside the component tree.

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

type DatabaseTool = Tool & {
  readonly connectionString: string; // custom extra field
};

const Postgres: DatabaseTool = {
  id: "postgres",
  name: "PostgreSQL",
  connectionString: "postgresql://localhost:5432/mydb",
  fields: [{ name: "connectionString", label: "Connection String", required: true }],
};

// ToolCard infers T = DatabaseTool, so tool.connectionString is accessible
<ToolCard<DatabaseTool> tool={Postgres} />

When you pass a plain Tool-shaped object, T defaults to Tool and no explicit type parameter is needed.

ToolCardProps

ToolCardProps is the full props type for the ToolCard component. It extends the underlying shadcn/ui Card props (minus children, which the card manages internally) and adds three ai-tool-elements-specific props.

import type { ToolCardProps } from "ai-tool-elements";
// ToolCardProps<T extends Tool> = Omit<ComponentProps<typeof Card>, "children"> & {
//   tool: T;
//   actions?: ReactNode;
//   footer?: ReactNode;
// }

Prop	Type	Description
`tool`	`T`	The connector definition to render
`actions`	`ReactNode`	Optional controls rendered in the card header (e.g. a connect button)
`footer`	`ReactNode`	Optional content rendered below the fields, separated by a top border
`className`	`string`	Forwarded to the root `Card` element for style overrides

All other props accepted by shadcn/ui’s Card component (such as style, aria-*, data-*) pass through unchanged.

Importing types

All types can be imported from the single package entry point. Use import type to ensure zero runtime overhead — the imports are erased entirely during compilation.

import type {
  Tool,
  ToolCatalogItem,
  ToolField,
  ToolImage,
  ToolCardProps,
} from "ai-tool-elements";

Use import type (instead of import) for type-only imports to ensure zero runtime overhead. TypeScript erases these imports entirely during compilation, so they never appear in the emitted JavaScript.

Get Started

Components

Tool Catalog

Guides

Complete TypeScript Type Reference for ai-tool-elements

Exported types

`ToolField`

`ToolImage`

`Tool`

`ToolCatalogItem`

Using the Tool type

ToolCard generics

ToolCardProps

Importing types

​Exported types

​ToolField

​ToolImage

​Tool

​ToolCatalogItem

​Using the Tool type

​ToolCard generics

​ToolCardProps

​Importing types

Exported types

`ToolField`

`ToolImage`

`Tool`

`ToolCatalogItem`

Using the Tool type

ToolCard generics

ToolCardProps

Importing types