---
title: "Components"
description: "Override built-in or add custom MDX components"
canonical_url: "https://docs.farming-labs.dev/docs/customization/components"
markdown_url: "https://docs.farming-labs.dev/docs/customization/components.md"
last_updated: "2018-10-20"
agent:
  tokenBudget: 1000
  task: "Register a custom MDX component or override a built-in component without breaking page rendering."
  outcome: "The component is available in MDX, receives the intended props, and renders in the configured docs theme."
  appliesTo:
    framework:
      - "nextjs"
      - "tanstackstart"
      - "sveltekit"
      - "astro"
      - "nuxt"
    version:
      - ">=0.2.60"
    package:
      - "@farming-labs/docs"
  prerequisites:
    - "The project has a working docs.config file and an existing docs page for verification."
    - "Use docs.config.tsx when registration includes JSX."
    - "Confirm whether the requirement needs a config component override or a theme default-prop override."
  files:
    - "components/info-card.tsx"
    - "docs.config.tsx"
    - "src/lib/docs.config.ts"
    - "app/docs/getting-started/page.mdx"
    - "docs/getting-started/page.mdx"
  sideEffects:
    - "Overriding a built-in component changes every docs page that renders that MDX element."
  verification:
    - description: "Build the docs app and render an MDX page that uses the component."
      expect: "The build succeeds, the component renders once with the documented props, and existing built-ins still work."
  rollback:
    - "Remove the component registration and restore the previous built-in or theme defaults."
  failureModes:
    - symptom: "MDX reports that the custom component is undefined."
      resolution: "Export the component, register the exact case-sensitive name in docs.config.tsx, and restart the dev server."
    - symptom: "The config fails to parse after adding a component."
      resolution: "Rename docs.config.ts to docs.config.tsx when the config contains JSX."
---

<!-- farming-labs:agent-contract:start -->
## Agent Contract

Task: Register a custom MDX component or override a built-in component without breaking page rendering.
Outcome: The component is available in MDX, receives the intended props, and renders in the configured docs theme.

### Applies To

- Framework: `nextjs`, `tanstackstart`, `sveltekit`, `astro`, `nuxt`
- Version: `>=0.2.60`
- Package: `@farming-labs/docs`

### Prerequisites

- The project has a working docs.config file and an existing docs page for verification.
- Use docs.config.tsx when registration includes JSX.
- Confirm whether the requirement needs a config component override or a theme default-prop override.

### Files

- `components/info-card.tsx`
- `docs.config.tsx`
- `src/lib/docs.config.ts`
- `app/docs/getting-started/page.mdx`
- `docs/getting-started/page.mdx`

### Side Effects

- Overriding a built-in component changes every docs page that renders that MDX element.

### Verification

- Build the docs app and render an MDX page that uses the component.
  - Expected: The build succeeds, the component renders once with the documented props, and existing built-ins still work.

### Rollback

- Remove the component registration and restore the previous built-in or theme defaults.

### Failure Modes

- MDX reports that the custom component is undefined. — Recovery: Export the component, register the exact case-sensitive name in docs.config.tsx, and restart the dev server.
- The config fails to parse after adding a component. — Recovery: Rename docs.config.ts to docs.config.tsx when the config contains JSX.
<!-- farming-labs:agent-contract:end -->

# Components

## Components task

Task: Register a custom MDX component or override a built-in component without breaking page rendering.

Expected result: The component is available in MDX, receives the intended props, and renders in the configured docs theme.

Exact implementation:

```tsx title="docs.config.tsx"
import { defineDocs } from "@farming-labs/docs";
import { pixelBorder } from "@farming-labs/theme/pixel-border";
import { InfoCard } from "./components/info-card";

export default defineDocs({
  // ...theme, nav, etc.
  components: {
    InfoCard,
  },
});
```
## Components prerequisites

- The project has a working docs.config file and an existing docs page for verification.
- Use docs.config.tsx when registration includes JSX.
- Confirm whether the requirement needs a config component override or a theme default-prop override.
- Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs.

## Components verification

- Build the docs app and render an MDX page that uses the component. Expected: The build succeeds, the component renders once with the documented props, and existing built-ins still work.
- Failure: MDX reports that the custom component is undefined.
- Recovery: Export the component, register the exact case-sensitive name in docs.config.tsx, and restart the dev server.
- Rollback: Remove the component registration and restore the previous built-in or theme defaults.

## Components agent guidance

For Next.js or TanStack Start, create the React component and register its exact case-sensitive name
under top-level `components` in `docs.config.ts[x]`; MDX can then use that name without an import.
Astro, SvelteKit, and Nuxt use their adapter-native component registration instead. Use
`theme.ui.components` only to change default props for a built-in; a top-level entry such as
`components.HoverLink` replaces that component across the React-rendered docs pages.

Build the docs app and render one MDX page with the documented props while confirming existing
built-ins still work. If MDX reports an undefined component, check its export and registration name
and restart the dev server. If JSX makes the config fail to parse, rename `docs.config.ts` to
`docs.config.tsx`. Remove a built-in override to restore the previous component; when removing a
custom component, remove its MDX usages too.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).