Componentes para projetos Astro
Componentes Astro para copiar para o seu projeto. Cada ficha traz o código, as props aceitas e o que precisa estar instalado para ele funcionar.
Breadcrumbs
Mostre o caminho até a página atual com um componente Breadcrumbs em Astro, com a lista ordenada, o aria-current no último item e nenhum JavaScript.
Informe na prop items a lista de links do início até a página atual.
Numa página três níveis abaixo da home, como um post dentro de uma categoria, o visitante perde a noção de onde está e não tem como voltar um nível sem usar o botão do navegador. O Breadcrumbs devolve essa orientação com uma linha de links do início até a página atual.
O código
Crie o arquivo src/components/Breadcrumbs.astro com este código:
---interface Item { label: string href: string}interface Props { items: Item[]}const { items } = Astro.props---<nav aria-label="Você está aqui"> <ol class="breadcrumbs"> {items.map((item, index) => ( <li> {index === items.length - 1 ? ( <span aria-current="page">{item.label}</span> ) : ( <a href={item.href}>{item.label}</a> )} </li> ))} </ol></nav>
<style> .breadcrumbs { display: flex; flex-wrap: wrap; gap: 0.5rem; margin: 0; padding: 0; list-style: none; } .breadcrumbs li + li::before { content: '/'; margin-right: 0.5rem; color: #6b7280; }</style>Como usar
---import Breadcrumbs from '../components/Breadcrumbs.astro'---
<Breadcrumbs items={[ { label: 'Início', href: '/' }, { label: 'Blog', href: '/blog/' }, { label: 'Meu post', href: '/blog/meu-post/' }]} />O último item da lista vira texto com aria-current="page", sem link. Leitores de tela anunciam esse item como a página atual. A barra entre os itens vem do CSS (::before), então ela não é lida em voz alta.
Confira o resultado
Abra a página e confira que só o último item não é clicável. Com o leitor de tela do sistema, a navegação aparece com o nome “Você está aqui”.
O código desta ficha compilou com o Astro 7.4.7 no template Basics, em 5 de novembro de 2026.
CartaoPost
Liste posts com um cartão em Astro que leva o link no card inteiro, mostra a data em português e mantém um único destino para os leitores de tela.
Passe título, resumo, endereço e data do post. Use dentro do map da sua listagem.
Numa listagem de blog, o visitante tenta clicar no card inteiro e só o título responde. O CartaoPost estende o link do título por todo o card com um ::after, sem envolver o card num <a> gigante que leitores de tela leem de uma vez.
O código
Crie o arquivo src/components/CartaoPost.astro com este código:
---interface Props { title: string description: string href: string date: Date}const { title, description, href, date } = Astro.propsconst dataFormatada = new Intl.DateTimeFormat('pt-BR', { dateStyle: 'long' }).format(date)---<article class="cartao"> <h2><a href={href}>{title}</a></h2> <p>{description}</p> <time class="cartao__data" datetime={date.toISOString()}>{dataFormatada}</time></article>
<style> .cartao { position: relative; padding: 1.5rem; border: 1px solid #e5e7eb; border-radius: 0.75rem; } .cartao h2 { margin: 0 0 0.5rem; font-size: 1.25rem; } .cartao a::after { content: ''; position: absolute; inset: 0; } .cartao a:focus-visible { outline: 2px solid currentColor; outline-offset: 4px; } .cartao__data { color: #6b7280; font-size: 0.875rem; }</style>Como usar
---import { getCollection } from 'astro:content'import CartaoPost from '../components/CartaoPost.astro'const posts = await getCollection('blog')---
{posts.map((post) => ( <CartaoPost title={post.data.title} description={post.data.description} href={`/blog/${post.id}/`} date={post.data.pubDate} />))}A data sai formatada por Intl.DateTimeFormat em pt-BR, como “5 de novembro de 2026”. O atributo datetime do elemento de data guarda a data no formato ISO, que buscadores leem.
Confira o resultado
Clique em qualquer ponto do card e confira que ele abre o post. Navegue com Tab e veja o contorno de foco ao redor do título.
O código desta ficha compilou com o Astro 7.4.7 no template Basics, em 5 de novembro de 2026.
CopiarCodigo
Mostre um comando com botão de copiar em Astro, usando um custom element com JavaScript mínimo e aviso para leitores de tela quando a cópia acontece.
Passe o texto do comando na prop code.
Num tutorial, um comando colado errado vem de uma seleção que pegou um espaço a mais ou deixou um caractere de fora. Um botão de copiar evita esse erro. Este componente mostra o código e liga o botão só quando o navegador oferece a API de área de transferência.
O código
Crie o arquivo src/components/CopiarCodigo.astro com este código:
---interface Props { code: string}const { code } = Astro.props---<copiar-codigo> <pre><code>{code}</code></pre> <button type="button" hidden>Copiar</button> <p role="status" aria-live="polite"></p></copiar-codigo>
<script> class CopiarCodigo extends HTMLElement { connectedCallback() { const button = this.querySelector('button') const code = this.querySelector('code') const status = this.querySelector('[role="status"]') if (!button || !code || !status || !navigator.clipboard) return button.hidden = false button.addEventListener('click', async () => { try { await navigator.clipboard.writeText(code.textContent ?? '') status.textContent = 'Código copiado.' } catch { status.textContent = 'Não foi possível copiar. Selecione o código e copie pelo teclado.' } }) } } customElements.define('copiar-codigo', CopiarCodigo)</script>Como usar
---import CopiarCodigo from '../components/CopiarCodigo.astro'---
<CopiarCodigo code="npm create astro@latest" />O botão começa com hidden e só aparece depois que o script confirma navigator.clipboard. Sem JavaScript, você ainda vê e seleciona o código. O parágrafo com role="status" anuncia “Código copiado.” para leitores de tela.
Confira o resultado
Clique no botão, cole no terminal e confira o comando. Desative o JavaScript no navegador e veja que o código continua na página, sem o botão.
O código desta ficha compilou com o Astro 7.4.7 no template Basics, em 5 de novembro de 2026.
SeoHead
Gere title, description, URL canônica e tags de Open Graph de cada página com um componente SeoHead em Astro, montado a partir do site do astro.config.mjs.
Coloque o componente dentro do head do layout e passe title, description e, se houver, o caminho da imagem de compartilhamento.
Quando o link de uma página é colado no WhatsApp ou no LinkedIn sem as tags de Open Graph, a prévia sai sem título certo e sem imagem. A URL canônica ausente faz o buscador tratar endereços com e sem barra final como páginas diferentes. O SeoHead cobre os dois casos num lugar só.
O código
Crie o arquivo src/components/SeoHead.astro com este código:
---interface Props { title: string description: string image?: string}const { title, description, image } = Astro.propsconst canonicalURL = new URL(Astro.url.pathname, Astro.site)const imageURL = image ? new URL(image, Astro.site) : undefined---<title>{title}</title><meta name="description" content={description} /><link rel="canonical" href={canonicalURL} /><meta property="og:type" content="website" /><meta property="og:url" content={canonicalURL} /><meta property="og:title" content={title} /><meta property="og:description" content={description} />{imageURL && <meta property="og:image" content={imageURL} />}<meta name="twitter:card" content={imageURL ? 'summary_large_image' : 'summary'} />Como usar
---import SeoHead from '../components/SeoHead.astro'---
<head> <meta charset="utf-8" /> <SeoHead title="Como publicar um site Astro" description="Build estático na pasta dist e adapter para as rotas sob demanda." image="/og/publicar.png" /></head>A URL canônica sai de new URL(Astro.url.pathname, Astro.site), a mesma construção da referência oficial. Sem a opção site no astro.config.mjs, o Astro.site fica undefined. O componente quebra o build. Preencha antes:
export default defineConfig({ site: 'https://seusite.com.br'})Confira o resultado
Rode npm run build e abra o HTML da página em dist/. A tag <link rel="canonical"> precisa trazer o endereço completo, com o seu domínio.
O código desta ficha compilou com o Astro 7.4.7 no template Basics, em 5 de novembro de 2026.
ImagemResponsiva
Sirva cada imagem no tamanho certo para a tela com um componente que usa o Image do astro:assets e o layout constrained, com srcset gerado no build.
Importe a imagem de src/assets e informe o texto alternativo e as dimensões máximas.
Uma foto de 3000 pixels servida inteira para um celular de 400 pixels de largura deixa a página pesada e derruba a nota de performance. O componente usa o Image do Astro para gerar as versões menores no build e deixar o navegador escolher a certa.
O código
Crie o arquivo src/components/ImagemResponsiva.astro com este código:
---import { Image } from 'astro:assets'import type { ImageMetadata } from 'astro'
interface Props { src: ImageMetadata alt: string width: number height: number caption?: string}const { src, alt, width, height, caption } = Astro.props---<figure> <Image src={src} alt={alt} layout="constrained" width={width} height={height} /> {caption && <figcaption>{caption}</figcaption>}</figure>Como usar
---import ImagemResponsiva from '../components/ImagemResponsiva.astro'import capa from '../assets/capa.jpg'---
<ImagemResponsiva src={capa} alt="Painel do projeto aberto no navegador" width={800} height={600} caption="O painel depois da publicação." />Com layout="constrained", o Astro gera o srcset e o sizes sozinho, a partir da largura máxima informada. O alt é obrigatório no componente Image. Sem ele, o build falha e aponta o arquivo.
Confira o resultado
No build, abra a página e inspecione a tag <img>. Ela precisa ter srcset, sizes, width e height. O arquivo servido sai da pasta /_astro/.
O código desta ficha compilou com o Astro 7.4.7 no template Basics, em 5 de novembro de 2026.