Shortcut

O componente Shortcut é usado para criar atalhos de navegação rápida com ícones, labels e descrições opcionais.

Importação

import { Shortcut } from '@useblu/ocean-react';

Importação específica (recomendado para tree-shaking)

import { Shortcut } from '@useblu/ocean-react/Shortcut';

Importação de tipos TypeScript

import type { ShortcutProps } from '@useblu/ocean-react';

// Uso em componente customizado
const MyComponent: React.FC<ShortcutProps> = (props) => {
  return <Shortcut {...props} />;
};

Playground Interativo

Explore o componente Shortcut no playground interativo do Storybook:

🚀 Abrir no Storybook

Documentação Completa

Para documentação técnica detalhada, exemplos de uso e API completa, consulte o Storybook do Shortcut.

No Storybook você encontrará:

• ✅ Controles interativos para testar todas as props
• ✅ API gerada automaticamente com tipagem completa
• ✅ Exemplos visuais de todas as variantes e estados
• ✅ Playground para experimentação rápida

Uso básico

O Shortcut é usado para criar atalhos de navegação:

<Shortcut
  label="Meu Atalho"
  description="Descrição do atalho"
  icon={<PlaceholderOutline />}
/>

Tamanhos

O Shortcut está disponível em três tamanhos diferentes:

Tiny

<Shortcut label="Tiny" icon={<PlaceholderOutline />} size="tiny" />

Small

<Shortcut label="Small" icon={<PlaceholderOutline />} size="small" />

Medium (padrão)

<Shortcut
  label="Medium"
  description="Com descrição"
  icon={<PlaceholderOutline />}
  size="medium"
/>

Veja todos os tamanhos juntos:

🚀 Abrir no Storybook

Orientação

O Shortcut pode ser exibido em orientação horizontal ou vertical:

Horizontal (padrão)

<Shortcut
  label="Horizontal"
  description="Orientação horizontal"
  icon={<PlaceholderOutline />}
  orientation="horizontal"
/>

Vertical

<Shortcut
  label="Vertical"
  description="Orientação vertical"
  icon={<PlaceholderOutline />}
  orientation="vertical"
/>

Comparação entre orientações:

🚀 Abrir no Storybook

Estados

Normal

<Shortcut label="Normal" icon={<PlaceholderOutline />} />

Bloqueado

<Shortcut label="Bloqueado" icon={<PlaceholderOutline />} blocked />

Desabilitado

<Shortcut label="Desabilitado" icon={<PlaceholderOutline />} disabled />

Veja todos os estados:

🚀 Abrir no Storybook

Badge e Tag

O Shortcut pode exibir um badge numérico ou uma tag. As propriedades count e tag são mutuamente exclusivas - você deve usar apenas uma por vez.

Com Badge

O badge exibe um número e aparece no canto superior do atalho:

<Shortcut label="Com Badge" icon={<PlaceholderOutline />} count={5} />

Com Tag

A tag exibe um texto e sua posição depende da orientação do atalho:

Tag em orientação horizontal

Na orientação horizontal (padrão), a tag aparece ao lado do label, dentro do conteúdo:

<Shortcut
  label="Com Tag"
  icon={<PlaceholderOutline />}
  tag="Novo"
  orientation="horizontal"
/>

Tag em orientação vertical

Na orientação vertical, a tag aparece acima do conteúdo:

<Shortcut
  label="Com Tag"
  icon={<PlaceholderOutline />}
  tag="Novo"
  orientation="vertical"
/>

Exemplos de Badge e Tag:

🚀 Abrir no Storybook

🚀 Abrir no Storybook

Full Width

Use a prop fullWidth para fazer o Shortcut ocupar toda a largura disponível:

<div style={{ width: '300px' }}>
  <Shortcut
    label="Atalho Normal"
    description="Sem fullWidth"
    icon={<PlaceholderOutline />}
  />
  <Shortcut
    label="Atalho Full Width"
    description="Com fullWidth ativado"
    icon={<PlaceholderOutline />}
    fullWidth
  />
</div>

Comparação Full Width:

🚀 Abrir no Storybook

API

Props

Prop	Tipo	Padrão	Descrição
label	string	-	Texto do label do atalho
description	string	-	Descrição adicional (apenas para size medium)
icon	ReactNode	-	Ícone do atalho
size	'tiny' | 'small' | 'medium'	'medium'	O tamanho do componente de atalho
orientation	'horizontal' | 'vertical'	'horizontal'	A orientação do layout do atalho
blocked	boolean	false	Define se o atalho está bloqueado
disabled	boolean	false	Desabilita o atalho
fullWidth	boolean	false	Faz o atalho ocupar toda a largura disponível
count	number	-	Número exibido no badge do atalho (mutuamente exclusivo com tag)
tag	string	-	Tag exibida no atalho (mutuamente exclusivo com count). Posição varia com orientation
className	string	-	Classes CSS adicionais

Classes CSS

O componente Shortcut utiliza as seguintes classes CSS para customização:

Classes principais

Classe	Descrição
.ods-shortcut	Classe base do componente
.ods-shortcut--tiny	Tamanho tiny do atalho
.ods-shortcut--small	Tamanho small do atalho
.ods-shortcut--medium	Tamanho medium do atalho (padrão)
.ods-shortcut--horizontal	Orientação horizontal (padrão)
.ods-shortcut--vertical	Orientação vertical
.ods-shortcut--blocked	Estado bloqueado do atalho
.ods-shortcut--disabled	Estado desabilitado do atalho
.ods-shortcut--full-width	Atalho ocupa toda a largura disponível
.ods-shortcut--with-badge	Atalho com badge numérico

Classes de elementos internos

Classe	Descrição
.ods-shortcut__icon	Container do ícone
.ods-shortcut__content	Container do conteúdo (ícone + label)
.ods-shortcut__content--horizontal	Layout horizontal do conteúdo
.ods-shortcut__content--vertical	Layout vertical do conteúdo
.ods-shortcut__label	Texto do label
.ods-shortcut__description	Texto da descrição
.ods-shortcut__badge	Container do badge numérico
.ods-shortcut__tag	Container da tag (posição varia)
.ods-shortcut__blocked	Container do ícone de bloqueio

Acessibilidade

• ✅ Suporte completo a navegação por teclado
• ✅ Estados de foco visíveis
• ✅ Atributos ARIA apropriados
• ✅ Suporte a screen readers
• ✅ Contraste adequado em todos os estados

Navegação por teclado

Tecla	Função
Tab	Move o foco para o atalho
Space / Enter	Ativa o atalho

Melhores práticas

✅ Faça

• Use labels claros e concisos que descrevam a ação
• Use ícones que representem visualmente a funcionalidade
• Use descrições apenas quando necessário para esclarecimento
• Use badges para notificações numéricas importantes
• Use tags para destacar status ou categorias importantes
• Escolha a orientação adequada ao layout (horizontal ou vertical)
• Considere a posição da tag ao escolher a orientação

❌ Não faça

• Não use textos muito longos nos labels
• Não use ícones que não representem a funcionalidade
• Não use badge (count) e tag (tag) ao mesmo tempo - são mutuamente exclusivos
• Não omita o estado disabled quando apropriado
• Não use Shortcut para ações que não são navegação

Visão geral completa

Veja todas as variantes do Shortcut em ação:

🚀 Abrir no Storybook

Links relacionados

• Button - Para ações principais
• Badge - Para notificações numéricas
• Tag - Para categorização
• Storybook - Shortcut - Documentação técnica