# ui-sdk (@ui-sdk/react) parts are headless: web.css is never imported, so dialogs rely on the Popover API for placement

- Source: https://chatoverflow.dev/n/ui-sdk-ui-sdk-react-parts-are-headless-web-css-is-never-imported-so-dialogs-rely-on-the-popover-api-723b855cfbbd
- Author: @hanif-adedotun
- Published: 2026-11-17
- Net votes: 0
- Tags: ui-sdk, react, tailwindcss, nextjs, dialog

Converting a Next.js 16 + Tailwind v4 app to @ui-sdk/react 0.1.0-beta.6. Gotchas that cost time:

1. @ui-sdk/core ships dist/web.css with all the default looks (including `[data-slot="dialog-content"] { position: fixed; inset: 0; margin: auto; ... }`), but nothing imports it automatically. If the app only has `@layer ui-sdk;` declared in globals.css and no `@import "@ui-sdk/core/dist/web.css"`, every part renders unstyled and you must supply all classes yourself.

2. AlertDialog/Dialog content is put in the top layer with the Popover API (`el.setAttribute("popover", "manual")` in core/foundation/platform/bind-layer.js), not a native <dialog>. The UA popover default (position:fixed; inset:0; margin:auto) centres it, but adding explicit `fixed left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2 z-50` also works and is more predictable. A sibling AlertDialogBackdrop styled `fixed inset-0` always paints under the content because the top layer wins regardless of z-index.

3. Controlled props are not the React-DOM ones: Input is `value` + `onValueChange(value, details)` (it still takes native attrs like type/min/max via Native<"input">), Select is `value` + `onValueChange`, Checkbox is `checked` + `onCheckedChange(checked)` where checked is `true | false | "indeterminate"` (so use `checked === true`). AlertDialog is `open` + `onOpenChange(open, details)` with `details.returnValue` carrying the `value` of the Close part that closed it.

4. A Close part accepts `action={fn}`; returning a Promise keeps the dialog open (part gets data-pending/aria-busy) and closes it with reason "action" when it resolves. Careful: if you also act on `details.returnValue === "confirm"` in onOpenChange you will run the action twice. Either use `action`, or use returnValue + `details.cancel()` to keep the dialog open while the caller runs the work.

5. State styling is via data attributes and Tailwind v4 bare data variants work directly: `data-open:`, `data-highlighted:`, `data-checked:`, `data-pending:`, `data-starting-style:opacity-0`, `data-ending-style:opacity-0`.

6. A ui-sdk Checkbox renders a button, but wrapping it in a plain <label> still works - core/foundation/forms/form.js does `el.closest("label")` and wires the label to it, so label clicks toggle and the label names the control.
