Item

Layout

Linha genérica de lista, composta por partes (mídia, título, descrição, ações), para resultados de busca e listas de configuração.

Carregando

Instalação

Recebe correções por update de versão. O caminho recomendado.

npm i @trdr/ui

import { Item } from "@trdr/ui/item"

Uso

import { Item, ItemActions, ItemContent, ItemDescription, ItemFooter, ItemGroup } from "@trdr/ui/item"

export function Exemplo() {
  return <Item />
}

Variantes

GrupoValoresPadrão
variant
defaultoutlinemuted
default
size
defaultsm
default

Props

ItemPropsestende React.HTMLAttributes<HTMLDivElement>, VariantProps<typeof itemVariants>
PropTipoDescrição
asChild?booleanRenderiza o filho no lugar da <div>, tipicamente um <a> para a linha inteira virar link.
ItemMediaPropsestende React.HTMLAttributes<HTMLDivElement>, VariantProps<typeof itemMediaVariants>
ItemContentPropsestende React.HTMLAttributes<HTMLDivElement>
ItemTitlePropsestende React.HTMLAttributes<HTMLDivElement>
ItemDescriptionPropsestende React.HTMLAttributes<HTMLParagraphElement>
ItemActionsPropsestende React.HTMLAttributes<HTMLDivElement>
ItemHeaderPropsestende React.HTMLAttributes<HTMLDivElement>
ItemFooterPropsestende React.HTMLAttributes<HTMLDivElement>
ItemGroupPropsestende React.HTMLAttributes<HTMLDivElement>
ItemSeparatorPropsestende React.ComponentPropsWithoutRef<typeof SeparatorPrimitive.Root>

Quando usar

Use o Item para qualquer linha de lista que combine um pedaco de midia (icone, avatar, imagem), um titulo, opcionalmente uma descricao, e opcionalmente uma acao: um resultado de busca, um item de configuracao, uma linha de notificacao, uma conta numa lista de contas. Ele nao existe no Hub legado porque o legado nao tinha um primitivo generico para isso, cada tela reimplementava a propria linha do zero.

Use ItemGroup quando varios Item formam uma lista coerente (uma lista de resultados, um menu de configuracoes), e ItemSeparator entre eles quando a lista precisa de uma linha divisoria visivel em vez de so espacamento.

Quando nao usar

Nao use Item para uma linha de tabela: dados tabulares com colunas alinhadas (preco, quantidade, horario) sao trabalho do Table, que traz alinhamento numerico e cabecalho proprios. Nao use Item para um card autocontido que precisa de borda e sombra proprias como unidade isolada fora de uma lista: nesse caso o Card e a peca certa. Item e feito para conviver em sequencia dentro de um ItemGroup, nao para flutuar sozinho como bloco de destaque.

Anatomia

  • Item (data-slot="item"): a raiz da linha, com variant e size. Aceita asChild para a linha inteira virar um <a> navegavel.
  • ItemMedia (data-slot="item-media"): o icone, avatar ou imagem no inicio da linha. Variantes default (sem fundo), icon (moldura quadrada com fundo) e image (recorte circular para foto). Quando a linha tem ItemDescription, a midia sobe para o topo automaticamente, porque a linha fica mais alta.
  • ItemContent (data-slot="item-content"): a coluna de texto, ocupa o espaco restante da linha.
  • ItemTitle (data-slot="item-title"): o titulo da linha.
  • ItemDescription (data-slot="item-description"): o texto de apoio, corta em duas linhas com reticencias quando nao cabe.
  • ItemActions (data-slot="item-actions"): botoes ou indicadores no fim da linha.
  • ItemHeader / ItemFooter (data-slot="item-header" / "item-footer"): faixas que ocupam a linha inteira, para quando o item precisa de uma area de topo (titulo mais uma etiqueta de status) ou de rodape (metadado mais uma acao) alem da linha principal de midia e conteudo.
  • ItemGroup (data-slot="item-group"): envolve varios Item em coluna.
  • ItemSeparator (data-slot="item-separator"): linha divisoria fina entre itens de um grupo.

Variantes

  • variant: default (fundo transparente, realce so no hover), outline (borda visivel o tempo todo, para linhas que precisam se destacar mesmo sem interacao) e muted (fundo preenchido, para o item selecionado ou em destaque).
  • size: default e sm, controlando o espacamento interno da linha.

Acessibilidade

Quando asChild transforma a linha num <a>, o nome acessivel do link vem do texto visivel dentro dele (tipicamente ItemTitle mais ItemDescription): garanta que esse texto sozinho ja diz para onde o link leva. Icones dentro de ItemMedia que so decoram (nao carregam informacao que o texto da linha ja nao diga) devem ter aria-hidden="true". Quando ItemActions tem um botao so com icone, ele precisa do proprio aria-label, igual a qualquer botao icone fora do Item. ItemGroup nao carrega role="list": o conteudo de um Item e livre (pode ter um botao, um link, qualquer coisa), e a regra de acessibilidade que exige filhos listitem dentro de um role="list" nao combina com isso. Quando a lista precisa mesmo da semantica de lista para o leitor de tela, envolva o ItemGroup num <ul>/<li> real por fora, ou numa <nav> quando for navegacao.

Slots e tokens

Todo elemento renderizado carrega um data-slot para estilizar partes internas sem depender de classe da biblioteca. Os tokens listados são extraídos do código fonte.

[data-slot="item"][data-slot="item-actions"][data-slot="item-content"][data-slot="item-description"][data-slot="item-footer"][data-slot="item-group"][data-slot="item-header"][data-slot="item-media"][data-slot="item-separator"][data-slot="item-title"]
15 tokens usados
bg-border-subtlebg-surface-secondarybg-transparentborder-border-subtleborder-transparentoutline-nonering-offset-2ring-offset-backgroundring-ringtext-b3text-b4text-content-primarytext-content-secondarytext-content-tertiarytext-l3