Avara UI
Avara UI

API Playground

A highly advanced, interactive split-pane block for testing API requests directly inside documentation.
This is the hallmark of top-tier developer platforms (like Stripe, Supabase, or Vercel). Instead of showing static code blocks, this component allows users to adjust headers, parameters, and JSON payloads, and hit "Send" to see formatted responses.
Crucially, this ApiPlaygroundBlock uses a mockHandler pattern. It does not blindly send network requests (which usually fail due to CORS in documentation environments). Instead, you define exactly how the component should respond to different inputs, creating a safe, curated learning experience.
Each playground below is fully interactive: edit params, headers or the JSON body, then hit Send. Nothing leaves the browser — a mockHandler decides the response.

API playground

A split-pane request builder.

PassmockHandler
an async function — it receives the method, url, headers, params and body, and returns { status, timeMs, data } for the response pane to render.
defaultUrl
seeds the address bar the reader lands on.

Installation

New project? Follow the installation guide to set up Tailwind CSS, shadcn, the cn helper and lucide-react, register the @algorize-ui registry once, then copy your styles from the Themes page.

Install API Playground

npx shadcn@latest add @algorize-ui/api-playground

components/custom/blocks/ApiPlaygroundBlock.tsx is written into your project. Copy any snippet from a Usage tab above and it runs.

Install dependencies

Step 1 installs this for you. Run it yourself only if you are adding API Playground to an existing project by hand. The cn helper and lucide-react are not listed — the installation guide covers them once for every component.

select is a component, not a package — the shadcn CLI installs it as source files.

npx shadcn@latest add @algorize-ui/select

Features & Core Capabilities

Explore the interactive API Playground component capabilities designed to elevate API documentation:

Split-Pane Architecture

Interactive dual-panel interface with real-time HTTP Request Builder on the left and Live JSON Response Viewer on the right.

CORS-Safe Mock Handler

Uses a client-side mockHandler async function to simulate network latency, dynamic endpoints, and custom status codes safely without CORS issues.

Full Header & Query Params Editor

Add, enable/disable, or remove HTTP headers and query parameters dynamically before executing API calls.

JSON Body Payload & Syntax Highlighting

Built-in raw JSON request body editor with syntax highlighting, automatic JSON formatting, error handling, and response timing metrics.

Best Practices & Guidelines

Usage Guidelines

Provide realistic mock handlers with simulated delays (e.g. 100ms - 500ms) to give users an authentic API testing experience directly inside your documentation.

Props Reference

PropTypeDefaultDescription
defaultUrlstring"https://api.example.com/v1/users"Initial API URL displayed in the request address bar.
defaultMethod"GET" | "POST" | "PUT" | "PATCH" | "DELETE""GET"Initial HTTP method selected in the method dropdown.
colorApiColor"primary"Accent color theme ("primary" | "indigo" | "rose" | "emerald" | "zinc" or custom hex).
mockHandlerApiMockHandlerundefinedAsync function that receives request details and returns simulated API response data.
classNamestringundefinedAdditional CSS classes applied to the root container.

mockHandler Object Signatures

When you provide a mockHandler, your function receives a Request object and must return a Promise that resolves to a Response object. Both shapes are exported, so annotate the whole handler and TypeScript infers the rest — no need to restate them:
The Request Object — exported as ApiPlaygroundRequest (passed to your function):
The Response Object — exported as ApiResponse (required return type):