Pular para o conteúdo
Sobreposição

Sheet

/componentes/sheet.mdmarkdown cru, para quem lê com agent em vez de olho

Folha de baixo

Lateral

Ações presas embaixo

Importar
import { Sheet } from '@rivocode/ui'

Quando usar

Folha que desliza da borda da tela, com gesto de arrastar.

Compõe com SheetTrigger, SheetContent, SheetTitle, SheetDescription, SheetHandle, SheetFooter e SheetClose.

side decide de onde ela entra, e o gesto de fechar segue o lado. É a peça de navegação no celular e o painel de ações onde o polegar alcança. O tipo é SheetSide, e são três lados: bottom, left e right. Não há top, porque folha que desce do alto disputa com a barra de status do celular e com todo cabeçalho fixo.

Sem side, o lado sai da largura: bottom abaixo de 640px, onde a ação fica ao alcance do polegar, e right acima, ao lado do conteúdo que a folha detalha. O detalhe de uma consulta ou o filtro de uma listagem não precisa de mais nada. Passe o lado quando ele não pode mudar: left na navegação, bottom no painel de ações que é de baixo em toda largura. O SheetHandle é de folha de baixo, e só desenha nela: na folha lateral ele não renderiza nada, então a mesma árvore com SheetHandle serve para a folha que é de baixo no celular e da direita na mesa.

<Sheet open={open} onOpenChange={setOpen}>
  <SheetContent>
    <SheetTitle>Consulta de 05/08</SheetTitle>
  </SheetContent>
</Sheet>

As ações vão no SheetFooter, por último. Ele gruda na borda de baixo enquanto o conteúdo rola, e a ação fica ao alcance mesmo no detalhe comprido. Rodapé feito à mão com sticky bottom-0 gruda acima do respiro do painel, e o que rola aparece na fresta embaixo dele.

<SheetContent>
  <SheetTitle>Pedido #1044</SheetTitle>
  <DescriptionList>
    <DescriptionItem label="Cliente">Marina Albuquerque</DescriptionItem>
    <DescriptionItem label="Total">R$ 63,00</DescriptionItem>
  </DescriptionList>
  <SheetFooter>
    <SheetClose render={<Button variant="secondary" />}>Fechar</SheetClose>
    <Button>Confirmar pedido</Button>
  </SheetFooter>
</SheetContent>

A tarja de fundo clareia junto com o dedo: puxar pela metade mostra metade do que está atrás.

O espaço entre os filhos vai em classNames.content. O className do SheetContent veste o painel: o fundo, a borda, o respiro. Os filhos moram numa caixa dentro dele, então flex flex-col gap-6 no className não chega ao título nem ao formulário, e o título encosta no primeiro campo. O layout dos filhos vai na caixa deles:

<SheetContent classNames={{ content: 'flex flex-col gap-6' }}>
  <SheetTitle>Novo cliente</SheetTitle>
  <Field>
    <FieldLabel>Nome</FieldLabel>
    <Input name="nome" />
  </Field>
  <SheetFooter>
    <Button>Salvar cliente</Button>
  </SheetFooter>
</SheetContent>

A largura

size mede a folha de lado: sm 20rem (o padrão), md 28rem, lg 40rem e full, a janela inteira. As três primeiras param em 85% da janela (90% no lg), para sobrar a borda da página e o toque de fora que fecha. O tipo é SheetSize. md serve o detalhe com uma tabela curta ou um formulário de duas colunas; lg, a ficha que o usuário compara com a lista atrás; full, o fluxo que toma a tela sem deixar de ser folha.

<Sheet side="right" size="lg">
  <SheetContent>
    <SheetTitle>Pedido #1044</SheetTitle>
  </SheetContent>
</Sheet>

Na folha de baixo a largura já é a da tela, então só o full muda alguma coisa: ela ocupa a altura inteira em vez de parar em 85%, sem o canto arredondado.

Quando não usar

Para uma decisão curta, use Dialog, e para o que não tem volta, AlertDialog. A folha é para o detalhe e o trabalho ao lado do conteúdo, e não para uma pergunta.

Quando lista e detalhe ficam sempre lado a lado, é Splitter, que não cobre nada. Painel pequeno preso a um botão, como o filtro de dois campos na mesa, é Popover. E tarefa que ocupa a tela inteira merece página própria.

No React Native

Traduz: só o comportamento de baixo, que já era o modo estreito do web, e por isso sem o size da folha de lado. Sobe deslizando, e sem transição quando o sistema pede para reduzir movimento; com campo dentro, a folha sobe junto com o teclado. title é opcional, com label no lugar quando o Result toma a folha, e scrollable faz o conteúdo rolar com o título parado.

Arrastar para baixo fecha, como no web. O painel segue o dedo e o fundo clareia junto; ao soltar depois de 30% da altura da folha, ou num peteleco rápido, ela chama onOpenChange(false), e antes disso volta para o lugar. Para cima ela não cresce. O arrasto nasce só do puxador e do cabeçalho, e nunca do corpo, para não disputar com a lista que rola dentro dela. Com reduzir movimento o painel não acompanha o dedo, e o arrasto longo fecha do mesmo jeito. Select, Combobox, Menu e os seletores de data ganham o gesto sem prop nenhuma.

swipeToClose={false} desliga o gesto, para quando o topo da folha já tem gesto próprio na vertical. O fundo, o voltar do Android e o gesto de escape do VoiceOver continuam fechando, e o puxador continua sendo desenho, sem foco.

No iOS e no Android. A peça cobre a tela inteira, por cima da barra de status e da de navegação, e mede a área segura do aparelho com o react-native-safe-area-context, o mesmo número nos dois, e não a da tela, que a navegação zera embaixo do cabeçalho. No Android, o voltar do sistema fecha a folha. O iOS não tem voltar: fecha-se pelo fundo, arrastando a folha para baixo ou pelo gesto de escape do VoiceOver.

API

PropTipoPadrão
actionsRef0.4.0

Uma ref para as ações imperativas.

RefObject<DrawerRootActions | null>sem padrão
defaultOpen0.4.0

Se a gaveta começa aberta.

booleanfalse
defaultSnapPoint0.4.0

O ponto de parada inicial, no modo não controlado.

DrawerSnapPoint | nullsem padrão
defaultTriggerId0.4.0

ID do gatilho ao qual a gaveta está associada.

string | nullsem padrão
disablePointerDismissal0.4.0

Se a gaveta não fecha com o toque de fora.

booleanfalse
handle0.4.0

Um identificador que associa a gaveta a um gatilho.

DrawerHandle<unknown>sem padrão
modal0.4.0

Se a gaveta aberta fica em estado modal.

"trap-focus" | booleantrue
onOpenChange0.4.0

Chamado quando a gaveta abre ou fecha.

((open: boolean, eventDetails: DrawerRootChangeEventDetails) => void)sem padrão
onOpenChangeComplete0.4.0

Chamado depois que as animações terminam, quando a gaveta abre ou fecha.

((open: boolean) => void)sem padrão
onSnapPointChange0.4.0

Chamado quando o ponto de parada muda.

((snapPoint: DrawerSnapPoint | null, eventDetails: DrawerRootSnapPointChangeEventDetails) => void)sem padrão
open0.4.0

Se a gaveta está aberta agora.

booleansem padrão
side0.4.0

De onde a folha entra.

SheetSidesem padrão
size

A largura da folha de lado: `sm` 20rem, o padrao, `md` 28rem, `lg` 40rem, todas presas a 85vw (90vw no `lg`) para sobrar a borda da pagina, e `full` a janela inteira.

SheetSize"sm"
snapPoint0.4.0

O ponto de parada ativo agora.

DrawerSnapPoint | nullsem padrão
snapPoints0.4.0

Os pontos de parada onde a gaveta pode assentar.

DrawerSnapPoint[]sem padrão
snapToSequentialPoints0.4.0

Desliga o pulo de parada pela velocidade, e a distância do arraste decide o próximo ponto.

booleanfalse
triggerId0.4.0

ID do gatilho ao qual a gaveta está associada.

string | nullsem padrão

Partes

Sheet se monta com estas peças. Todas vivem nesta página, porque separar cada uma num endereço obrigaria a abrir seis abas para montar uma tela.

SheetClose

/sheet-close.md

Fecha a folha de dentro dela. Use render para emprestar o comportamento ao botão que já existe no rodapé, em vez de somar mais um.

PropTipoPadrão
nativeButton0.4.0

Se a peça renderiza um `<button>` nativo quando é trocada pela prop `render`.

booleantrue
render0.4.0

Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente.

ComponentRenderFn<HTMLProps, DrawerCloseState> | ReactElement<unknown, string | JSXElementConstructor<any>>sem padrão

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

SheetContent

/sheet-content.md

O painel, com a tarja de fundo e o portal por dentro.

Monta em portal no container do RivoProvider, então o tema vale ali dentro. Não recebe side: o lado mora na raiz, porque o gesto de fechar tem que concordar com a direção de onde a folha entrou.

A tarja é irmã do painel dentro do portal, então nem className nem variante de descendente alcançam ela. Para vestir as duas, use classNames com as partes backdrop e viewport.

PropTipo
classNames0.5.0

Classe por parte: `backdrop`, `viewport` e `content`.

Partial<Record<"backdrop" | "content" | "viewport", string>>
finalFocus0.4.0

O elemento que recebe o foco quando a gaveta fecha.

booleanRefObject<HTMLElement | null>((closeType: InteractionType) => void | boolean | HTMLElement | null)
initialFocus0.4.0

O elemento que recebe o foco quando a gaveta abre.

booleanRefObject<HTMLElement | null>((openType: InteractionType) => void | boolean | HTMLElement | null)
render0.4.0

Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente.

ComponentRenderFn<HTMLProps, DrawerPopupState> | ReactElement<unknown, string | JSXElementConstructor<any>>

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

SheetDescription

/sheet-description.md

A linha de contexto embaixo do título, ligada ao painel por aria-describedby.

PropTipo
render0.4.0

Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente.

ComponentRenderFn<HTMLProps, DrawerDescriptionState> | ReactElement<unknown, string | JSXElementConstructor<any>>

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

SheetFooter

/sheet-footer.md

A fila de ações da folha, presa na borda de baixo enquanto o conteúdo rola.

Vai por último dentro do SheetContent. O detalhe comprido rola por baixo dele, e a ação continua ao alcance do polegar sem a pessoa descer até o fim. Ele encosta na borda de verdade, por cima do respiro do painel e da área do gesto do celular: o rodapé escrito à mão com sticky bottom-0 gruda acima do respiro, e o que rola aparece na fresta embaixo dele.

A ação que confirma vai por último na marcação. No celular os botões empilham em largura cheia e a ordem se inverte, com quem confirma no alto e quem fecha rente ao polegar: o mesmo comportamento do DialogFooter.

Sem prop própria: repassa ao elemento de baixo o que você mandar.

SheetHandle

/sheet-handle.md

A barrinha de pegar, só na folha de baixo.

É o único aviso de que dá para arrastar. Sem ela o gesto continua existindo e ninguém descobre, e aí a única saída visível é o clique fora, que na folha de baixo fica no meio do conteúdo que a pessoa veio ler.

Sai escondida do leitor de tela: quem navega por teclado fecha com Esc, e uma barra decorativa anunciada só atrapalha.

Sem prop própria: repassa ao elemento de baixo o que você mandar.

SheetTitle

/sheet-title.md

O título da folha, e o nome dela para o leitor de tela.

Folha sem título é um painel que se abre sem dizer o que é: quem usa leitor de tela ouve só "diálogo". Quando o desenho não comporta título visível, o aria-label no SheetContent faz o papel.

PropTipo
render0.4.0

Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente.

ComponentRenderFn<HTMLProps, DrawerTitleState> | ReactElement<unknown, string | JSXElementConstructor<any>>

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

SheetTrigger

/sheet-trigger.md

O que abre a folha. Use render para emprestar o gatilho a um Button, em vez de aninhar um botão dentro de outro.

PropTipoPadrão
handle0.4.0

Um identificador que associa o gatilho a uma gaveta.

DrawerHandle<Payload>sem padrão
nativeButton0.4.0

Se a peça renderiza um `<button>` nativo quando é trocada pela prop `render`.

booleantrue
payload0.4.0

Um dado a entregar à gaveta quando ela abre.

Payloadsem padrão
render0.4.0

Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente.

ComponentRenderFn<HTMLProps, DrawerTriggerState> | ReactElement<unknown, string | JSXElementConstructor<any>>sem padrão

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.