Componentes React personalizados
Defina e use componentes React personalizados em arquivos MDX com renderização no servidor, estilização com Tailwind e acesso aos componentes integrados do Jamdesk.
Defina componentes React personalizados diretamente em arquivos MDX. Exporte um componente de função de seta no início do arquivo e use-o inline. Os componentes são renderizados no servidor durante o build. Eles podem usar qualquer componente integrado do Jamdesk e classes do Tailwind.
Uso básico
Defina um componente usando export const no início do seu arquivo MDX:
export const Highlight = ({ children, color }) => (
<span style={{ backgroundColor: color, padding: '0.2em 0.4em', borderRadius: '4px' }}>
{children}
</span>
);
This text has a <Highlight color="#ffeb3b">yellow highlight</Highlight> in it.
Os nomes dos componentes devem usar PascalCase (começar com letra maiúscula).
Exemplo: cartão hero
Este exemplo usa várias props e classes do Tailwind:
export const HeroCard = ({ title, description, href, icon }) => (
<a
href={href}
className="group block p-6 rounded-lg border border-gray-200 hover:border-blue-500 transition-colors"
>
<div className="flex items-center gap-3 mb-2">
<Icon icon={icon} />
<h3 className="font-semibold text-lg">{title}</h3>
</div>
<p className="text-gray-600">{description}</p>
</a>
);
<div className="grid grid-cols-2 gap-4">
<HeroCard
title="Getting started"
description="Learn the basics"
href="/quickstart"
icon="rocket"
/>
<HeroCard
title="Components"
description="Explore available components"
href="/components/overview"
icon="puzzle-piece"
/>
</div>
Como usar componentes integrados
Componentes personalizados podem usar qualquer componente integrado do Jamdesk sem necessidade de import:
export const FeatureCard = ({ title, children }) => (
<Card title={title} icon="star">
{children}
<Tip>This tip is inside a custom component!</Tip>
</Card>
);
<FeatureCard title="My Feature">
<Note>Notes work inside custom components too!</Note>
</FeatureCard>
Componentes integrados por categoria:
| Categoria | Componentes |
|---|---|
| Callouts | Note, Tip, Info, Warning, Check, Danger |
| Layout | Card, Columns, Tabs, Tab, Accordion, Steps, Step, View |
| Mídia | Frame, Icon, Badge, Tooltip |
| Código | CodeGroup |
| Documentação de API | ParamField, ResponseField, Expandable |
Limitações
- Apenas funções de seta: use a sintaxe
export const. A sintaxeexport functionnão é suportada. - Sem imports: não é possível importar pacotes externos nem outros arquivos
- Sem hooks: hooks do React (
useState,useEffect,useRef, etc.) não estão disponíveis. Os componentes são renderizados no servidor durante o build. Hooks funcionam apenas no lado do cliente. Use arquivos de snippet para componentes interativos (veja a solução de problemas abaixo). - Apenas no servidor: os componentes são renderizados no servidor. Não há interatividade no lado do cliente nem manipuladores de eventos
- Somente Tailwind: estilize com classes utilitárias do Tailwind CSS. CSS-in-JS não está disponível
- Sintaxe estrita: um erro de sintaxe em um componente inline faz o build falhar com uma mensagem de erro clara
- Nomes em PascalCase: os nomes dos componentes devem começar com letra maiúscula e conter apenas letras e números (sem sublinhados)
Precisa de hooks do React? Componentes inline não podem usar useState, useEffect ou outros hooks. Eles são renderizados no servidor durante o build. Crie um arquivo de snippet com a diretiva 'use client' para componentes que precisam de estado ou efeitos (veja a seção de solução de problemas abaixo).
Práticas recomendadas
Componentes inline devem ser apenas de apresentação. Solicite um componente integrado para lógica complexa.
Crie componentes acessíveis com elementos HTML adequados e atributos ARIA.
Visualize sua documentação localmente. Verifique se os componentes também são renderizados corretamente no modo escuro.
Solução de problemas
Error: Expected component 'MyComponent' to be defined
Causes:
- Component name doesn't use PascalCase (must start with capital letter)
- Syntax error in the component definition
- Missing closing tag or parenthesis
Solution: Check that your export follows this pattern:
export const MyComponent = ({ prop }) => (
<div>{prop}</div>
);Error: Build fails mentioning Babel or JSX syntax
Causes:
- Invalid JSX syntax in your component
- Unclosed tags or brackets
- Using unsupported JavaScript features
Solution: Verify your JSX is valid. Common issues:
- All tags must be closed (
<img loading="lazy" />not<img loading="lazy">) - Use
classNameinstead ofclass - Wrap multiple elements in a fragment
<>...</>or parent element
Warning: Inline component(s) override built-in: Note
Cause: Your inline component has the same name as a built-in component.
Solution: Rename your component to avoid conflicts:
// Instead of: export const Note = ...
export const CustomNote = ({ children }) => (
<div className="my-note">{children}</div>
);Issue: Tailwind classes aren't working
Causes:
- Using CSS-in-JS or inline style objects (limited support)
- Tailwind class not included in the build
Solution: Use standard Tailwind utility classes. Use an inline style prop with simple values for custom styles:
export const Highlight = ({ children }) => (
<span style={{ backgroundColor: '#ffeb3b' }}>{children}</span>
);Issue: Component defined with export function doesn't render
Cause: Only export const arrow function syntax is supported.
Solution: Convert your function to arrow function syntax:
// Instead of:
export function MyComponent({ prop }) {
return <div>{prop}</div>;
}
// Use:
export const MyComponent = ({ prop }) => (
<div>{prop}</div>
);Issue: Component with underscores or special characters doesn't work
Cause: Component names must be valid PascalCase identifiers (letters and numbers only).
Solution: Use only letters and numbers in your component name:
// Instead of: export const Hero_Card = ...
// Instead of: export const my-component = ...
export const HeroCard = ({ title }) => (
<div>{title}</div>
);Error: ReferenceError: useState is not defined
Cause: React hooks are not available in inline components. Inline components are server-rendered during the build. Hooks only work in client-side React components.
Solution: Create a snippet file for interactive components that need state or effects:
- Create a file in your
/snippetsdirectory (e.g.,/snippets/counter.tsx) - Add
'use client'at the top of the file - Import and use it in your MDX
'use client';
import { useState } from 'react';
export function Counter() {
const [count, setCount] = useState(0);
return (
<button onClick={() => setCount(c => c + 1)}>
Count: {count}
</button>
);
}import { Counter } from '/snippets/counter';
<Counter />