> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Primitivos

> Controles fundamentales para crear interfaces con Twenty UI.

## Resumen

Los primitivos son los controles fundamentales de Twenty UI. Incluyen entradas, elementos de visualización, navegación y controles compuestos como Select, Popover y AlertDialog. Cada primitivo recibe datos y funciones de devolución de llamada de tu aplicación.

Importa primitivos desde un punto de entrada de familia, como `twenty-ui/primitives/input`. La entrada agregada `twenty-ui/primitives` también exporta todas las familias de primitivas. Consulta [Primeros pasos](https://docs.twenty.com/es/ui/getting-started.md) para obtener información sobre la instalación y la configuración del tema.

Los [componentes](https://docs.twenty.com/es/ui/components/overview) combinan estas primitivas en preajustes de diseño compartidos y bloques de creación de aplicaciones reutilizables.

## Propiedad del estado

Usa el estado no controlado cuando un componente pueda gestionar sus propias interacciones. Una prop predeterminada proporciona el estado inicial. Usa el estado controlado cuando la aplicación necesite coordinar ese estado con otros controles, la navegación o los datos de la aplicación.

| Estado | Estado inicial no controlado | Estado controlado | Callback de cambio |
| - | - | - | - |
| Entrada, selección o pestaña activa | `defaultValue` | `valor` | `onValueChange` |
| Casilla de verificación o interruptor | `defaultChecked` | `checked` | `onCheckedChange` |
| Visibilidad de la ventana emergente | `defaultOpen` | `open` | `onOpenChange` |

En el modo controlado, pasa el estado actual y actualízalo en el callback de cambio. En el modo no controlado, aún puedes escuchar los cambios sin asumir la propiedad del estado. Agregar solo un callback no hace que un componente sea controlado.

Elige un modo para cada estado y mantenlo durante toda la vida útil del componente. Las props predeterminadas inicializan el estado; cambiarlas más adelante no reemplaza el estado actual. Evita pasar tanto la prop predeterminada como la controlada para el mismo estado.

Algunos componentes tienen más de un estado independiente. Por ejemplo, [Select](https://docs.twenty.com/es/ui/primitives/input/select.md#open-state) puede tener un valor controlado y una visibilidad de ventana emergente no controlada.

El estado pertenece a la parte que gestiona la interacción. Configura la selección de botones de opción en [RadioGroup](https://docs.twenty.com/es/ui/primitives/input/radio-group.md), no en cada Radio. Los componentes de visualización, como Text, no tienen un modo controlado ni no controlado. [Toast](https://docs.twenty.com/es/ui/components/feedback/toast.md) delega su visibilidad y eliminación a la aplicación.

## Composición

Los componentes primitivos compuestos exponen partes como `Select.Root`, `Select.Trigger` y `Select.Popup`. Mantenga las partes relacionadas bajo la misma raíz en el árbol de componentes para que compartan el estado y las relaciones de accesibilidad. La sección de anatomía de cada componente identifica las partes obligatorias y el contenido opcional.

Los slots como `InputGroup.startElement` y `ListItem.actions` aceptan nodos de React como props. Añaden contenido dentro del diseño de un componente. Las partes y los slots son API diferentes; use los nombres indicados en la guía del componente.

### Composición de ventanas emergentes

Select, Popover y Autocomplete exponen partes independientes de `Portal`, `Positioner` y `Popup`:

| Parte | Responsabilidad |
| - | - |
| `Portal` | Contenedor de destino y montaje |
| `Positioner` | Posicionamiento, ancla, desplazamientos y gestión de colisiones |
| `Popup` | Contenido, comportamiento del foco, atributos nativos y ref |
| `Arrow` | Flecha opcional dentro de la ventana emergente |

Anida Popup dentro de Positioner y Positioner dentro de Portal. Coloca el contenido dentro de Popup y añade Arrow explícitamente cuando sea necesario. El portal puede mover el DOM renderizado a otro contenedor mientras conserva la jerarquía y el contexto de los componentes. Consulte [la tematización](https://docs.twenty.com/es/ui/theming.md#scope-an-override) para los contenedores de portal con ámbito.

Cada parte renderizada conserva sus propios atributos nativos, destino de ref y composición de renderizado. [Autocomplete](https://docs.twenty.com/es/ui/primitives/input/autocomplete) también conserva las partes de colección, agrupación, cuadrícula, filtrado y estado ascendentes instaladas.

[Dialog](https://docs.twenty.com/es/ui/primitives/surfaces/dialog.md) y [AlertDialog](https://docs.twenty.com/es/ui/primitives/surfaces/alert-dialog.md) exponen partes independientes de `Portal`, `Backdrop`, `Viewport` y `Popup`. Configure el montaje y el destino en Portal, la apariencia de la superposición en Backdrop y Viewport, y el tamaño y el foco del contenido en Popup. Cada parte conserva sus propios atributos nativos, destino de ref y composición de renderizado. Estas API de diálogo son para la interfaz de usuario independiente y el host de Twenty. Los componentes Front usan la [API de diálogo del host de SDK](https://docs.twenty.com/es/developers/extend/apps/layout/front-components.md#host-communication-api).

### Componentes personalizados

Para las partes que admiten `render`, pase un elemento o componente compatible para reemplazar el elemento predeterminado. Por ejemplo, `Popover.Trigger` puede usar un `Button` de Twenty UI y conservar su comportamiento de activador.

Un contenedor personalizado debe pasar los props y la ref proporcionados al elemento interactivo. Esto conserva los controladores de eventos, los atributos de accesibilidad, el posicionamiento y la restauración del foco. Este ejemplo los reenvía mediante `Button`, que los adjunta a su botón nativo.

```tsx theme={null}
import { type ComponentPropsWithRef } from 'react';
import { Button } from 'twenty-ui/primitives/input';
import { Popover } from 'twenty-ui/primitives/surfaces';

type HelpButtonProps = ComponentPropsWithRef<typeof Button>;

const HelpButton = ({ ref, ...props }: HelpButtonProps) => (
  <Button {...props} ref={ref} variant="outline" />
);

export const ImportHelp = () => (
  <Popover.Root>
    <Popover.Trigger render={<HelpButton>Import help</HelpButton>} />
    <Popover.Portal>
      <Popover.Positioner>
        <Popover.Popup>
          <Popover.Title>Import a CSV file</Popover.Title>
          <Popover.Description>
            Use a header row to identify your columns.
          </Popover.Description>
          <Popover.Close render={<Button>Got it</Button>} />
        </Popover.Popup>
      </Popover.Positioner>
    </Popover.Portal>
  </Popover.Root>
);
```

Pase el botón mediante `render` y mantenga cada acción como un único control interactivo. Conserve los controladores y la ref proporcionados a su contenedor al añadir su propio comportamiento. La ref debe llegar al elemento que recibe el foco.

Use un botón nativo para las partes similares a botones. En las partes que exponen `nativeButton`, establezca `nativeButton={false}` solo cuando el elemento renderizado no sea un botón nativo. Un componente personalizado que finalmente renderiza un botón, como `HelpButton`, conserva el comportamiento predeterminado del botón.

## Explorar primitivas

Cada página incluye ejemplos de uso, orientación sobre la interacción y una referencia de API generada.

| Familia | Primitivas |
| - | - |
| Accesibilidad | [Oculto visualmente](https://docs.twenty.com/es/ui/primitives/accessibility/visually-hidden.md) |
| Datos en pantalla | [Avatar](https://docs.twenty.com/es/ui/primitives/data-display/avatar.md), [Ficha](https://docs.twenty.com/es/ui/primitives/data-display/chip.md), [Muestra de color](https://docs.twenty.com/es/ui/primitives/data-display/color-sample.md), [Insignia](https://docs.twenty.com/es/ui/primitives/data-display/badge.md), [Estado](https://docs.twenty.com/es/ui/primitives/data-display/status.md), [Etiqueta](https://docs.twenty.com/es/ui/primitives/data-display/tag.md) |
| Retroalimentación | [Banner](https://docs.twenty.com/es/ui/primitives/feedback/banner.md), [Cargador](https://docs.twenty.com/es/ui/primitives/feedback/loader.md), [Progreso](https://docs.twenty.com/es/ui/primitives/feedback/progress.md), [Barra de progreso](https://docs.twenty.com/es/ui/primitives/feedback/progress-bar.md), [Anillo de progreso](https://docs.twenty.com/es/ui/primitives/feedback/progress-ring.md), [Esqueleto](https://docs.twenty.com/es/ui/primitives/feedback/skeleton.md) |
| Formularios | [Autocompletar](https://docs.twenty.com/es/ui/primitives/input/autocomplete), [Botón](https://docs.twenty.com/es/ui/primitives/input/button.md), [Grupo de botones](https://docs.twenty.com/es/ui/primitives/input/button-group.md), [Casilla de verificación](https://docs.twenty.com/es/ui/primitives/input/checkbox.md), [Campo](https://docs.twenty.com/es/ui/primitives/input/field.md), [Entrada](https://docs.twenty.com/es/ui/primitives/input/input.md), [Grupo de entradas](https://docs.twenty.com/es/ui/primitives/input/input-group.md), [Campo numérico](https://docs.twenty.com/es/ui/primitives/input/number-field.md), [Botón de opción](https://docs.twenty.com/es/ui/primitives/input/radio.md), [Grupo de botones de opción](https://docs.twenty.com/es/ui/primitives/input/radio-group.md), [Seleccionar](https://docs.twenty.com/es/ui/primitives/input/select.md), [Control deslizante](https://docs.twenty.com/es/ui/primitives/input/slider.md), [Interruptor](https://docs.twenty.com/es/ui/primitives/input/switch.md), [Área de texto](https://docs.twenty.com/es/ui/primitives/input/textarea.md) |
| Diseño | [Plegable](https://docs.twenty.com/es/ui/primitives/layout/collapsible.md), [Separador](https://docs.twenty.com/es/ui/primitives/layout/separator.md), [Controlador de redimensionamiento](https://docs.twenty.com/es/ui/primitives/layout/resize-handle.md), [Proveedor de dirección](https://docs.twenty.com/es/ui/primitives/layout/direction-provider.md) |
| Navegación | [Migas de pan](https://docs.twenty.com/es/ui/primitives/navigation/breadcrumb.md), [Elemento de lista](https://docs.twenty.com/es/ui/primitives/navigation/list-item.md), [Pestañas](https://docs.twenty.com/es/ui/primitives/navigation/tabs.md) |
| Superficies | [Diálogo de alerta](https://docs.twenty.com/es/ui/primitives/surfaces/alert-dialog.md), [Tarjeta](https://docs.twenty.com/es/ui/primitives/surfaces/card.md), [Diálogo](https://docs.twenty.com/es/ui/primitives/surfaces/dialog.md), [Ventana emergente](https://docs.twenty.com/es/ui/primitives/surfaces/popover.md), [Información sobre herramientas](https://docs.twenty.com/es/ui/primitives/surfaces/tooltip.md) |
| Tipografía | [Encabezado](https://docs.twenty.com/es/ui/primitives/typography/heading.md), [Texto desbordante con descripción emergente](https://docs.twenty.com/es/ui/primitives/typography/overflowing-text-with-tooltip.md), [Proveedor del modo de descripción emergente para texto desbordante](https://docs.twenty.com/es/ui/primitives/typography/overflowing-text-tooltip-mode-provider), [Atajo](https://docs.twenty.com/es/ui/primitives/typography/shortcut.md), [Texto](https://docs.twenty.com/es/ui/primitives/typography/text.md) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.