Jamdesk Documentation logo

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:

CategoriaComponentes
CalloutsNote, Tip, Info, Warning, Check, Danger
LayoutCard, Columns, Tabs, Tab, Accordion, Steps, Step, View
MídiaFrame, Icon, Badge, Tooltip
CódigoCodeGroup
Documentação de APIParamField, ResponseField, Expandable

Limitações

  • Apenas funções de seta: use a sintaxe export const. A sintaxe export function nã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

1
Mantenha os componentes simples

Componentes inline devem ser apenas de apresentação. Solicite um componente integrado para lógica complexa.

2
Use HTML semântico

Crie componentes acessíveis com elementos HTML adequados e atributos ARIA.

3
Teste exaustivamente

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 className instead of class
  • 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:

  1. Create a file in your /snippets directory (e.g., /snippets/counter.tsx)
  2. Add 'use client' at the top of the file
  3. Import and use it in your MDX
/snippets/counter.tsx
'use client';

import { useState } from 'react';

export function Counter() {
  const [count, setCount] = useState(0);
  return (
    <button onClick={() => setCount(c => c + 1)}>
      Count: {count}
    </button>
  );
}
your-page.mdx
import { Counter } from '/snippets/counter';

<Counter />

O que vem a seguir?

Snippets

Componentes reutilizáveis entre páginas, incluindo interativos com hooks

Visão geral dos componentes

Explore os componentes integrados