Blife UI

Introducción

useSelection es un hook diseñado para gestionar selecciones de elementos en modo simple o múltiple, con sincronización opcional frente a cambios en los datos originales.

Con este hook puedes:

Seleccionar, deseleccionar o alternar elementos.
Seleccionar todos o ninguno (en modo múltiple).
Sincronizar automáticamente la selección si el conjunto de datos cambia.
Verificar si todos, algunos o un elemento específico están seleccionados.

Su API está pensada para ser predecible y fácil de integrar en tablas, listas, grids u otros componentes interactivos.

Importacion

import { useSelection } from "@blifedesarrollo/hooks";

Demo

Este ejemplo usa el componente DataTable de BlifeUI

Usuarios del Sistema

0 de 4 seleccionados

Nombre	Email	Rol	Estado
Juan Pérez	juan@email.com	Admin	Activo
María García	maria@email.com	Usuario	Inactivo
Carlos López	carlos@email.com	Usuario	Activo
Ana Rodríguez	ana@email.com	Moderador	Activo

Configuracion basica

function Demo() {
  const items = ["React", "Vue", "Angular", "Svelte"];
 
  const [selection, handlers] = useSelection({
    data: items, // Array de elementos(strings, numbers, objetos)
    mode: "multiple", // Modo de selección
  });
 
  return (
    <div>
      <p>Elementos seleccionados: {selection.join(", ")}</p>
    </div>
  );
}

Usando la Api

Seleccionar elementos

// Seleccionar un elemento específico
handlers.select("Vue");
 
// En modo 'single': reemplaza la selección actual
// En modo 'multiple': añade si no existe

Deseleccionar elementos

// Remover un elemento de la selección
handlers.deselect("React");
 
// El elemento se remueve sin importar el modo

Alternar selección

// Cambiar estado de selección
handlers.toggle("Angular");
 
// Si estaba seleccionado -> se deselecciona
// Si no estaba seleccionado -> se selecciona

Verificar selección

// Comprobar si un elemento está seleccionado
const isReactSelected = handlers.isSelected("React");
console.log(isReactSelected); // true o false
 
// Verificar estados globales
const allSelected = handlers.isAllSelected(); // ¿Todos seleccionados?
const someSelected = handlers.isSomeSelected(); // ¿Algunos seleccionados?

Operaciones en lote

// Seleccionar todos los elementos (solo modo 'multiple')
handlers.selectAll();
 
// Limpiar toda la selección
handlers.resetSelection();
 
// Establecer selección específica
handlers.setSelection(["React", "Vue"]);

Usando objetos como datos

Para objetos, el hook automáticamente compara el contenido completo de cada objeto:

import { useSelection } from "./hooks/useSelection";
 
function Demo() {
  // Array de objetos con múltiples propiedades
  const users = [
    { id: 1, name: "Ana García", role: "Admin", active: true },
    { id: 2, name: "Carlos López", role: "User", active: false },
    { id: 3, name: "María Silva", role: "Editor", active: true },
  ];
 
  const [selection, handlers] = useSelection({
    data: users,
    mode: "multiple",
  });
 
  return (
    <div>
      <p>Usuarios seleccionados: {selection.length}</p>
 
      {selection.length > 0 && (
        <div>
          <h4>Seleccionados:</h4>
          {selection.map((user) => (
            <div key={user.id}>
              {user.name} - {user.role}
            </div>
          ))}
        </div>
      )}
 
      {users.map((user) => (
        <div
          key={user.id}
          onClick={() => handlers.toggle(user)}
          data-checked={handlers.isSelected(user)}
        >
          <h4>{user.name}</h4>
        </div>
      ))}
    </div>
  );
}

Props

Parámetros

Prop	Tipo	Requerido	Descripción
`data`	`T[]`	Si	El array de elementos de los cuales seleccionar
`mode`	`'single' \| 'multiple'`	-	Modo de selección
`defaultSelection`	`T[]`	-	La selección inicial
`syncWithData`	`boolean`	-	Si es `true`, sincroniza la selección con cambios en data

Retorno

El hook retorna una tupla [selection, handlers]:

selection: T[] - La lista de los elementos actualmente seleccionados
handlers: UseSelectionHandlers<T> - Objeto con métodos para manejar la selección

Prop	Tipo	Descripción
`select`	`(value: T) => void`	Añade un elemento a la selección. En modo single reemplaza la selección
`deselect`	`(value: T) => void`	Remueve un elemento de la selección
`toggle`	`(value: T) => void`	Alterna el estado de selección de un elemento
`setSelection`	`(value: T[]) => void`	Establece la selección a un array específico de elementos
`resetSelection`	`() => void`	Limpia todas las selecciones
`selectAll`	`() => void`	Selecciona todos los elementos disponibles (solo en modo multiple)
`isSelected`	`(value: T) => boolean`	Verifica si un elemento específico está seleccionado
`isAllSelected`	`() => boolean`	Retorna true si todos los elementos del data están seleccionados
`isSomeSelected`	`() => boolean`	Retorna true si al menos un elemento del data está seleccionado

use-selection

Usuarios del Sistema