# Dynamic UI Components

> For AI: a map of Dynamic UI by purpose, plus the rules that prevent the most common errors. The exact contract of each component comes from the catalog, not from these docs.

---

## Where the exact contract comes from

The component catalog is the `api.json` of the Dynamic UI version this MCP pins. Two tools serve it:

| Tool | Use it to |
|------|-----------|
| `widgets-list-components` | List everything: components, then context providers, then hooks. Each entry has `name`, `description`, `propsCount` and `section` (`components`, `contexts` or `hooks`) |
| `widgets-get-component-props` | Get one full entry: props with types, defaults and descriptions, plus `types`, `forwardedProps`, `parent` and `accessor` when present. Accepts a component, a subcomponent by its own name or by its accessor (`DCardBody` or `DCard.Body`), a context provider or a hook. The response adds `name` (as requested), `key` (the catalog entry that matched) and `section` |

Stories with working snippets: `modyo://widgets/catalog/components` and `modyo://widgets/catalog/components/{componentId}`. Official composed examples: `modyo://widgets/catalog/patterns`.

Check a component with `widgets-get-component-props` before using a prop that is not in these docs.

---

## Rules that apply to every component

| Rule | Example |
|------|---------|
| Semantic color goes in `color` | `<DAlert color="danger">`, `<DButton color="secondary" />` |
| Button and badge text go in `text` | `<DButton text={t('common.save')} />`, `<DBadge text="New" />` |
| Most inputs pass the **value** to `onChange`, not an event | `DInput`, `DInputSearch`, `DInputPassword`, `DInputSwitch` (boolean), `DInputCurrency` (number) |
| Exceptions that pass the **event** | `DInputCheck` and `DInputRange` |
| `size` of `DButton` and `DBadge` is `sm` or `lg` | Omit it for the default size |
| Icons are Lucide names in PascalCase | `iconStart="Search"`, `icon="CreditCard"` — see `modyo://docs/widgets/components-icons` |
| Subcomponents are used through their accessor | `DCard.Body`, `DModal.Header`, `DTabs.Tab`, `DLayout.Pane`, `DListGroup.Item` |
| Modals and offcanvas open as portals | Register them in `availablePortals` and open them with `openPortal` — see `modyo://docs/widgets/components-overlay` |
| Visible text comes from `t('...')` | Required by the canonical template's ESLint configuration |

Some components forward extra props to the library they wrap (`forwardedProps` in the catalog entry): `DButton` and `DButtonIcon` to `<button>`, `DInput` to `<input>`, `DSelect` to react-select, `DDatePicker` to react-datepicker, `DInputMask` to its mask library, `DPaginator` and `DCarousel` to theirs. Those props are valid even though they are not listed under `props`.

---

## Components by purpose

| Purpose | Components | Doc |
|---------|------------|-----|
| Actions | `DButton`, `DButtonIcon` | `modyo://docs/widgets/components-buttons` |
| Text and number inputs | `DInput`, `DInputSearch`, `DInputPassword`, `DInputCurrency`, `DInputCounter`, `DInputCheck`, `DInputSwitch`, `DInputRange` | `modyo://docs/widgets/components-inputs` |
| Specialized inputs | `DInputMask`, `DInputPhone`, `DInputPin`, `DOtp`, `DPasswordStrengthMeter`, `DBoxFile` | `modyo://docs/widgets/components-inputs-advanced` |
| Selection | `DSelect`, `DInputSelect` | `modyo://docs/widgets/components-selects` |
| Dates | `DDatePicker` | `modyo://docs/widgets/components-date-time` |
| Feedback and states | `DAlert`, `DToast`, `DToastContainer`, `DBadge`, `DChip`, `DProgress`, `DSkeleton`, `DDataStateWrapper`, `DErrorBoundary` | `modyo://docs/widgets/components-feedback` |
| Layout and grouping | `DLayout`, `DCard`, `DBox`, `DCollapse`, `DListGroup` | `modyo://docs/widgets/components-layout` |
| Navigation | `DTabs`, `DStepper`, `DPaginator` | `modyo://docs/widgets/components-navigation` |
| Modals and side panels | `DModal`, `DOffcanvas` | `modyo://docs/widgets/components-overlay` |
| Anchored overlays | `DTooltip`, `DPopover`, `DDropdown` | `modyo://docs/widgets/components-overlay-widgets` |
| Icons | `DIcon` | `modyo://docs/widgets/components-icons` |
| Display | `DAvatar`, `DCurrencyText`, `DCreditCard`, `DVoucher`, `DTimeline`, `DCarousel` | `modyo://docs/widgets/components-other` |
| Hooks | 25 hooks: portals, toasts, confirmation, breakpoints, currency, selection, OTP, screenshots… | `modyo://docs/widgets/components-hooks` |
| Context | `DContextProvider` | `modyo://docs/widgets/components-hooks` |

Dynamic UI has no chart component.

---

## Before writing UI

1. Look for an official pattern in `modyo://widgets/catalog/patterns` (see `modyo://docs/widgets/INDEX`, Pattern Discovery).
2. Pick components from the table above and read their doc.
3. Confirm any prop you are not sure about with `widgets-get-component-props`.
