TypeScript SDK Type Reference for Content Blocks

@anthropic-ai/sdk types a Claude response's content as a discriminated union of content block types, keyed by a type field. This page is a quick reference for the block types you'll see most often in response.content, and the narrowing pattern TypeScript requires before you can touch a block-specific field.

How to Use This Reference

• Look up the block type by its .type string, then copy the narrowing snippet that matches how you're iterating (if-chain vs switch).
• Treat .type as the only field you can trust before narrowing. Every other field is specific to one member of the union.
• Use the comparison table as a lookup when reading someone else's loop over response.content and you need to know what a given block exposes.
• Remember there are two related unions: ContentBlock (what Claude sends you back) and block param types like ToolResultBlockParam (what you send to Claude when constructing messages). They are not interchangeable.

Content Block Types at a Glance

The union that types response.content includes other members beyond these three for less common cases (server-side tool activity, redacted thinking, and similar). The three above are the ones a typical response-handling loop narrows on.

TextBlock

TextBlock is Claude's ordinary reply text. It's the block type you'll narrow to most often.

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
 
const response = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Say hello in one sentence." }],
});
 
for (const block of response.content) {
  if (block.type === "text") {
    // TypeScript now knows `block` is a TextBlock here.
    console.log(block.text);
  }
}

ToolUseBlock

ToolUseBlock appears when Claude decides to call one of the tools you provided. .input is typed as unknown because its shape depends on the tool's own input_schema, so you still need to validate or cast it before use.

for (const block of response.content) {
  if (block.type === "tool_use") {
    // block.id, block.name, block.input are all available here.
    console.log(block.id, block.name, block.input);
  }
}

ThinkingBlock

ThinkingBlock carries Claude's extended thinking output. It only shows up in response.content when extended thinking is turned on for the request; otherwise it's simply absent, not present with an empty value.

for (const block of response.content) {
  if (block.type === "thinking") {
    console.log(block.thinking);
  }
}

Narrowing with a switch Statement

An if-chain works, but a switch on block.type reads better once you're handling three or more block types in the same loop, and it keeps each branch's narrowed type isolated:

for (const block of response.content) {
  switch (block.type) {
    case "text":
      console.log(block.text);
      break;
    case "tool_use":
      console.log(block.name, block.input);
      break;
    case "thinking":
      console.log(block.thinking);
      break;
    default:
      // Other block types in the union land here, unnarrowed.
      break;
  }
}

Filtering to One Block Type

When you only care about one block type, filter first instead of branching inside the loop. TypeScript narrows the array element type through a type predicate:

const toolCalls = response.content.filter(
  (block): block is Anthropic.ToolUseBlock => block.type === "tool_use"
);
 
for (const call of toolCalls) {
  console.log(call.name, call.input); // no further narrowing needed
}

Block Param Types Are a Separate Union

TextBlock, ToolUseBlock, and ThinkingBlock describe what Claude sends back to you. When you construct messages to send to Claude, you use the corresponding param types instead, such as ToolResultBlockParam for returning a tool's result. These param types are not the same TypeScript types as the response blocks, even where the names overlap, so don't reuse a ToolUseBlock you received as if it were valid input content.

const toolResultMessage: Anthropic.MessageParam = {
  role: "user",
  content: [
    {
      type: "tool_result",
      tool_use_id: call.id,
      content: "72°F and sunny",
    },
  ],
};

FAQs

Related

• The Anthropic TypeScript SDK Mental Model - how the client, requests, and responses fit together before you get to individual block types
• TypeScript/JavaScript SDK Basics - installing the SDK and making your first request
• Strongly Typed Tool Definitions with Zod in TypeScript - validating a ToolUseBlock's .input against a real schema
• TypeScript SDK Error Class Reference - the matching reference page for typed error classes instead of content blocks
• Handling Tool Use Requests and Returning Tool Result Blocks - the full round trip from ToolUseBlock to a ToolResultBlockParam response

Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5 - and the official @anthropic-ai/sdk TypeScript SDK (latest release). Model names, SDK versions, and pricing move quickly - verify current specifics at platform.claude.com/docs before relying on them.