Neon Documentation MDX Components Guide

A practical guide for the most commonly used MDX components in Neon documentation. This guide focuses on components you'll use most frequently when writing documentation.

Quick navigation

• Essential components - Most commonly used
• Tabbed content - CodeTabs and Tabs for organized content
• Content organization - Structure and navigation components
• Interactive elements - UI elements and forms
• Common shared components - Reusable content

Essential components

These are the most frequently used components in Neon docs.

Admonition

Callouts for notes, warnings, and tips. There are six types available: note (default), important, tip, info, warning, comingSoon.

<Admonition type="warning" title="Important">
Critical information requiring immediate attention.
</Admonition>

Live preview:

All Admonition types:

Steps

Numbered step-by-step instructions split by h2 headings.

<Steps>

## Get a Glass

Take a clean glass from the cabinet or dish rack.

## Turn on Tap

Adjust the faucet to your preferred temperature and flow rate.

## Fill and Drink

Fill the glass to desired level and enjoy your water.

</Steps>

Live preview:

1. Get a Glass

   Take a clean glass from the cabinet or dish rack.

2. Turn on Tap

   Adjust the faucet to your preferred temperature and flow rate.

3. Fill and Drink

   Fill the glass to desired level and enjoy your water.

Tabbed content

Components for organizing content into tabs.

CodeTabs

Multi-language code examples with tabs.

<CodeTabs labels={["JavaScript", "Python", "Go"]}>

```javascript
const { Client } = require('pg');
const client = new Client({
  connectionString: process.env.DATABASE_URL,
});
await client.connect();
```

```python
import psycopg2
import os

conn = psycopg2.connect(os.environ["DATABASE_URL"])
cur = conn.cursor()
```

```go
import (
    "database/sql"
    _ "github.com/lib/pq"
)

db, err := sql.Open("postgres", os.Getenv("DATABASE_URL"))
```

</CodeTabs>

Live preview:

const { Client } = require('pg');
const client = new Client({
  connectionString: process.env.DATABASE_URL,
});
await client.connect();

Tabs

General tabbed content (not just code). For code-specific tabs, use CodeTabs instead.

<Tabs labels={["Console", "CLI", "API"]}>
<TabItem>
Create a database using the Neon Console by navigating to your project dashboard and clicking "Create Database".
</TabItem>
<TabItem>
Use the Neon CLI to create a database:

```bash
neon databases create --name my-database
```

</TabItem>
<TabItem>
Use the API to create a database:

```bash
curl -X POST https://console.neon.tech/api/v2/projects/my-project/databases \
  -H "Authorization: Bearer $NEON_API_KEY"
```

</TabItem>
</Tabs>

Live preview:

Content organization

Components for structuring and organizing page content.

TechCards / DetailIconCards

Technology cards with icons, titles, and descriptions. These components use different icon systems - see the comparison table below to choose the right one.

TechCards

Standard technology cards layout using TechCards icons:

<TechCards>
  <a
    href="/docs/guides/node"
    title="Node.js"
    description="Connect Node.js applications to Neon"
    icon="node-js"
  >
    Node.js
  </a>
  <a
    href="/docs/guides/python"
    title="Python"
    description="Connect Python applications to Neon"
    icon="python"
  >
    Python
  </a>
  <a
    href="/docs/guides/nextjs"
    title="Next.js"
    description="Build Next.js apps with Neon"
    icon="next-js"
  >
    Next.js
  </a>
</TechCards>

Live preview:

• 

  Node.js

  Connect Node.js applications to Neon

• 

  Python

  Connect Python applications to Neon

• 

  Next.js

  Build Next.js apps with Neon

DetailIconCards

Alternative layout using DetailIconCards icons:

<DetailIconCards>
  <a
    href="/docs/ai/openai"
    title="OpenAI integration"
    description="Build AI features with OpenAI"
    icon="openai"
  >
    OpenAI Integration
  </a>
  <a
    href="/docs/ai/langchain"
    title="LangChain integration"
    description="Create AI workflows with LangChain"
    icon="langchain"
  >
    LangChain Integration
  </a>
  <a
    href="/docs/development"
    title="Code development"
    description="Development tools and practices"
    icon="code"
  >
    Code Development
  </a>
  <a
    href="/docs/cloud/aws"
    title="AWS integration"
    description="Deploy and scale with AWS"
    icon="aws"
  >
    AWS Integration
  </a>
</DetailIconCards>

Live preview:

• OpenAI Integration

  Build AI features with OpenAI

• LangChain Integration

  Create AI workflows with LangChain

• Code Development

  Development tools and practices

• AWS Integration

  Deploy and scale with AWS

DetailIconCards uses a different icon system than TechCards, which is why different icons are available._

TechCards vs DetailIconCards vs DocsList

Quick comparison to help you choose the right component:

DefinitionList

Accessible term/definition lists for defining technical terms and concepts.

<DefinitionList>

Database URL
: Connection string for your Neon database
: Format: `postgresql://user:password@host:port/database`

Connection Pool
: A cache of database connections
: Improves performance by reusing connections

Branch
: An isolated copy of your database
: Used for development and testing

</DefinitionList>

Live preview:

—Database URL

Connection string for your Neon database

Format: postgresql://user:password@host:port/database

—Connection Pool

A cache of database connections

Improves performance by reusing connections

—Branch

An isolated copy of your database

Used for development and testing

DocsList

Simple, clean lists for documentation links with optional theming. DocsList provides a lightweight alternative to card-based components for presenting navigation links or content summaries.

Props:

• title (string) - Optional title for the list section
• theme (string) - Visual theme: "docs" (document icon), "repo" (repository icon), or default (checkbox icon)

Default Theme (Checkbox Icon):

MDX Code:

<DocsList title="Related documentation">
  <a href="/docs/guides/node">Node.js Connection Guide</a>
  <a href="/docs/guides/python">Python Connection Guide</a>
  <a href="/docs/api-reference">API Reference</a>
  <a href="/docs/cli">CLI Documentation</a>
</DocsList>

Live preview:

Related documentation

• Node.js Connection Guide
• Python Connection Guide
• API Reference
• CLI Documentation

InfoBlock

InfoBlock creates a multi-column layout for organizing related content sections. It's particularly useful for creating "at-a-glance" summaries at the top of documentation pages, combining learning objectives with related resources. Use two columns.

Key Features:

• Commonly paired with DocsList for structured content presentation
• Ideal for page introductions and overview sections

Basic Two-Column Layout:

<InfoBlock>
<DocsList title="What you will learn:">
<p>How to view and modify data in the console</p>
<p>Create an isolated database copy per developer</p>
<p>Reset your branch to production when ready to start new work</p>
</DocsList>

<DocsList title="Related topics" theme="docs">
<a href="/docs/introduction/branching">About branching</a>
<a href="/docs/get-started-with-neon/workflow-primer">Branching workflows</a>
<a href="/docs/get-started-with-neon/connect-neon">Connect Neon to your stack</a>
</DocsList>
</InfoBlock>

Renders as:

Interactive elements

Components for user engagement and interaction.

CheckList

Interactive checklists for setup guides and tutorials. CheckList uses CheckItem components internally.

<CheckList title="Setup checklist">
  <CheckItem title="Create Neon account" href="#signup">
    Sign up for a free Neon account at console.neon.tech
  </CheckItem>
  <CheckItem title="Install dependencies" href="#install">
    Install the required packages for your project
  </CheckItem>
  <CheckItem title="Configure environment" href="#config">
    Set up your database connection string
  </CheckItem>
  <CheckItem title="Test connection" href="#test">
    Verify your application can connect to Neon
  </CheckItem>
</CheckList>

Live preview:

CheckItem

Individual checklist items used within CheckList components.

<CheckItem title="Task name" href="#anchor">
  Description of the task or requirement
</CheckItem>

Usage Notes:

• Always used within a <CheckList> component
• title prop is required
• href prop is optional for anchor linking
• Content is the description text

CTA (Call to Action)

Prominent call-to-action buttons for important actions.

<CTA
  title="Try Neon free"
  description="Start building with serverless Postgres today. No credit card required."
  buttonText="Sign Up"
  buttonUrl="https://console.neon.tech/signup"
/>

Live preview:

NeedHelp

Support widget for getting assistance.

<NeedHelp />

Live preview:

Common shared components

Reusable content components that load from shared templates.

LinkAPIKey

Link to API key management in the console.

<LinkAPIKey />

Live preview:

FeatureBetaProps

Status indicator for beta features with custom feature name.

<FeatureBetaProps feature_name="OpenTelemetry integration" />

Live preview:

Best practices

Component selection

• Admonition for important callouts
• Steps for sequential instructions
• CodeTabs for multi-language examples
• TechCards for technology showcases
• CheckList for setup guides
• InfoBlock for page introductions with multiple content sections
• DocsList for simple navigation lists with theming options

Content organization tips

• Use InfoBlock at the top of pages to provide quick orientation
• For TechCards, always check that the SVG file exists in /public/images/technology-logos/
• For DetailIconCards, use only icon names that are mapped in the component code
• Choose DocsList themes based on content type: default for tasks, docs for documentation, repo for code
• Use the comparison table to choose between TechCards, DetailIconCards, and DocsList

Component summary

This guide covers the most commonly used MDX components in Neon documentation. Each component includes:

• MDX syntax: Copy-paste ready code examples
• Live rendering: See exactly how components appear
• Props documentation: Available parameters and options
• Best practices: When and how to use each component

Component categories

For specialized components and specific use cases, see the Component Specialized Guide.