SplitButton

El componente SplitButton permite a las personas usuarias ejecutar acciones haciendo clic en un botón principal y mostrando un menú desplegable con acciones adicionales.

Default

Deshabilitado

Combina un botón principal con acciones secundarias en un menú desplegable.

import React from "react";
import { SplitButton } from "@nimbus-ds/components";

const Example: React.FC = () => (
  <SplitButton>
    <SplitButton.Primary>Add product</SplitButton.Primary>
    <SplitButton.Secondary>
      <SplitButton.Action>Add product and duplicate</SplitButton.Action>
      <SplitButton.Action>Add product from template</SplitButton.Action>
      <SplitButton.Action>Add multiple products</SplitButton.Action>
    </SplitButton.Secondary>
  </SplitButton>
);

export default Example;

Definición

El SplitButton es un componente compuesto que combina una acción principal con un conjunto de acciones secundarias relacionadas. Ofrece eficiencia al permitir ejecutar la acción más común directamente, y al mismo tiempo, acceder a opciones adicionales desde un menú desplegable. Es ideal para mantener la interfaz limpia sin sacrificar funcionalidades clave.

Anatomía del componente

El SplitButton se compone de:

Main Button: Ejecuta la acción predeterminada.
Secondary Button: Abre un Popover con acciones secundarias.
Popover: Contiene las opciones adicionales en un menú desplegable.

Dependencias

Este componente utiliza:

Popover - Para mostrar el menú desplegable con las acciones secundarias.
Icon - Para mostrar iconos en las opciones del menú.
Label - Para las etiquetas de texto en los botones y opciones.

Guidelines

Cuándo usar

Usá el SplitButton cuando:

Existe una acción principal clara y predecible (como "Guardar" o "Crear").
Existen acciones adicionales relacionadas, pero de menor frecuencia de uso.
Se quiere evitar ocupar múltiples espacios con botones secundarios.
Las acciones secundarias están contextualmente relacionadas con la acción principal.

Cuándo no usar

Evitá usarlo cuando:

No hay una acción principal destacada entre las opciones.
El menú contiene más de 4 opciones, ya que puede dificultar la navegación.
Las acciones del menú no están relacionadas entre sí.
Todas las acciones tienen la misma importancia.

Criterios de usabilidad y productividad

Minimiza el uso del mouse: Permite ejecutar la acción principal con Enter o click directo.
Optimiza el flujo de trabajo: Prioriza la opción más usada, reduciendo pasos.
Evita sobrecargar la interfaz: Agrupa acciones similares en un solo punto.
Facilita el descubrimiento: Las personas usuarias pueden explorar opciones relacionadas sin abandonar el contexto actual.

Accesibilidad

Navegación completa con teclado: Tab para foco, Enter para acción principal, flecha abajo para abrir menú.
Etiquetas claras y descripciones en cada opción del menú desplegable.
Roles ARIA: aria-haspopup="menu" en el botón desplegable.
Tamaños de click/tap mínimos: 32×32 px para cumplir con estándares de accesibilidad.
Indicadores de foco visibles para cada acción.
Evitar depender del color para distinguir estados.
Soporte para lectores de pantalla que comuniquen claramente la estructura y opciones disponibles.

Recomendaciones de uso

Agrupar acciones de exportación (Exportar como PDF, Exportar como Excel).
Combinar acciones de guardado (Guardar, Guardar y continuar, Guardar como borrador).
Gestionar acciones de creación (Crear producto, Crear producto y duplicar, Crear producto desde plantilla).

Componentes relacionados

Button - Puede ser usado para acciones individuales sin opciones secundarias.
Dropdown - Puede ser usado cuando todas las opciones tienen el mismo nivel de importancia.

Implementación

Instalá el componente via terminal.

npm install @nimbus-ds/split-button

Props

Las propiedades adicionales se pasan al elemento <SplitButton>. Consultá la documentación para ver la lista de atributos aceptados por el elemento <SplitButton>.

SplitButton

Name	Type	Default	Description
children*	React.ReactNode		The subcomponents (Primary and Secondary).
disabled	boolean	'false'	Disables the entire split button.
open	boolean		Controls the visibility of the popover.
onOpenChange	(open: boolean) => void;		Callback function to control popover opening and closing.
popoverPosition	'bottom' 'bottom-end' 'bottom-start' 'left' 'left-end' 'left-start' 'right' 'right-end' 'right-start' 'top' 'top-end' 'top-start'	'bottom-end'	Position of the popover relative to the button.