> ## 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. # Primitives > Foundational controls for building interfaces with Twenty UI. Primitives are the foundational controls in Twenty UI. They include inputs, display elements, navigation, and compound controls such as Select, Menu, and AlertDialog. Each primitive receives data and callbacks from your application. Import primitives from a family entry point, such as `twenty-ui/primitives/input`. See [Getting started](/ui/getting-started) for installation and theme setup. All existing UI controls belong to the primitives layer, including controls still being migrated to the new API. [Components](/ui/components/overview) are reserved for larger, reusable app building blocks composed from these primitives. ## State ownership Use uncontrolled state when a component can manage its own interactions. A default prop supplies the initial state. Use controlled state when the application needs to coordinate that state with other controls, navigation, or application data. | State | Uncontrolled initial state | Controlled state | Change callback | | ------------------------------- | -------------------------- | ---------------- | ----------------- | | Input, selection, or active tab | `defaultValue` | `value` | `onValueChange` | | Checkbox or switch | `defaultChecked` | `checked` | `onCheckedChange` | | Popup visibility | `defaultOpen` | `open` | `onOpenChange` | In controlled mode, pass the current state and update it in the change callback. In uncontrolled mode, you can still listen to changes without taking ownership of the state. Adding a callback alone does not make a component controlled. Choose a mode for each state and keep it for the lifetime of the component. Default props initialize state; changing them later does not replace the current state. Avoid passing both the default and controlled prop for the same state. Some components have more than one independent state. For example, [Select](/ui/primitives/input/select#open-state) can have a controlled value and uncontrolled popup visibility. [Menu](/ui/primitives/surfaces/menu#selection-and-submenus) can manage its own visibility while the application controls checkbox and radio selections. State belongs to the part that manages the interaction. Configure radio selection on [RadioGroup](/ui/primitives/input/radio-group), not on each Radio. Display components such as Text do not have a controlled or uncontrolled mode. [Toast](/ui/primitives/feedback/toast) delegates its visibility and removal to the application. ## Composition Compound primitives expose parts such as `Select.Root`, `Select.Trigger`, and `Select.Popup`. Keep related parts under the same root in the component tree so they share state and accessibility relationships. Each component's anatomy section identifies the required parts and optional content. Slots such as `InputGroup.startElement` and `ListItem.actions` accept React nodes as props. They add content within a component's layout. Parts and slots are different APIs; use the names listed in the component guide. ### Popup composition Twenty UI packages the supporting overlay elements inside each public `Popup` part: | Component | Included in `Popup` | Configure on `Popup` | | ------------- | -------------------------------------- | -------------------------------------------------------- | | `Select` | Portal and positioner | Placement, anchor, and portal container | | `Menu` | Portal and positioner | Placement, anchor, portal container, and mounting | | `Popover` | Portal, positioner, and optional arrow | Placement, anchor, portal container, mounting, and arrow | | `AlertDialog` | Portal, backdrop, and viewport | Size, portal container, mounting, and focus | Place content directly inside these popup parts. Their portal may move the rendered DOM to another container while preserving the component hierarchy and context. See [theming](/ui/theming#scope-an-override) for scoped portal containers. ### Custom components For parts that support `render`, pass a compatible element or component to replace the default element. For example, `Popover.Trigger` can use a Twenty UI `Button` while retaining its trigger behavior. A custom wrapper must pass the supplied props and ref to the interactive element. This preserves event handlers, accessibility attributes, positioning, and focus restoration. This example forwards them through `Button`, which attaches them to its native button. ```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; const HelpButton = ({ ref, ...props }: HelpButtonProps) => (