Search by

phem / ui-base

yceruto

Phem components that copy the behavior and the look of Base UI, styled with Tailwind CSS

Package info

github.com/phemphp/ui-base

Type:symfony-bundle

pkg:composer/phem/ui-base

Statistics

Installs: 1

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v0.1.0 2026-11-21 14:24 UTC

This package is auto-updated.

Last update: 2026-11-21 15:13:49 UTC


README

Phem components that copy the behavior and the look of Base UI. The .phem files hold the markup and the Tailwind classes. The browser behavior comes from the headless Stimulus controllers of phem/phem (phem-dialog, phem-menu, phem-combobox…). This package ships no JavaScript. A missing feature goes into phem, not into this package.

Use it in an app

composer require phem/ui-base

Import the theme in the Tailwind build, and enable the phem controllers in assets/controllers.json (see phem/docs/controllers.md). The theme file also adds the sources of the components to the build, so you need no @source for them:

@import "tailwindcss";
@import "../../vendor/phem/ui-base/assets/theme.css";
use Phem\Ui\Base\{Accordion, AccordionItem};
use function Phem\Ui\Base\{AccordionHeader, AccordionPanel, AccordionTrigger};

<Accordion>
    <AccordionItem value="what">
        <AccordionHeader><AccordionTrigger>What is Base UI?</AccordionTrigger></AccordionHeader>
        <AccordionPanel>A library of unstyled components.</AccordionPanel>
    </AccordionItem>
</Accordion>

Customize

The components take their colors, radius and popup shadow from CSS variables, with the names of shadcn/ui: bg-background, text-foreground, border-input, bg-primary… The default values give the look of the Tailwind demos of Base UI. The components have no dark: classes: the theme sets the dark values.

Change the theme

Set the variables in a rule after the import:

/* assets/styles/app.css */
@import "tailwindcss";
@import "../../vendor/phem/ui-base/assets/theme.css";

:root {
    --primary: oklch(0.55 0.2 260);
    --primary-foreground: oklch(0.98 0 0);
    --ring: oklch(0.55 0.2 260);
    --radius: 0.625rem;
}

Each <Checkbox>, <Switch>, <RadioGroup> and pressed <Toggle> is now blue, and each control and popup is round.

Variable Used for
--background, --foreground the box and the text of a control
--popover, --popover-foreground the box and the text of a popup: popover, menu, select, dialog, drawer, toast
--primary, --primary-foreground a checked, pressed or filled part: checkbox, switch, radio, toggle, slider, progress, meter
--accent, --accent-foreground the hover and the open state
--muted, --muted-foreground a track (avatar, meter, progress, scroll area); a description, a placeholder, a disabled text
--border the border of a popup and of a frame (accordion, fieldset), and the separator in a popup
--input the border of a control: button, input, select, checkbox, switch
--ring the focus outline
--destructive the error of a field
--radius the radius: rounded-popup is --radius, rounded-control is --radius * 0.8

phem/ui-base adds these variables. In the Base UI look, one shadcn color has two roles here:

Variable Default Used for
--highlight, --highlight-foreground --primary, --primary-foreground the highlighted item of a menu, a select or a combobox
--separator neutral-300 the <Separator> component
--accent-active --accent with 10% of --foreground a control while the pointer presses it (active:)
--overlay black / 20% the backdrop of a dialog
--popup-shadow an offset shadow, none in dark mode the shadow of a popup (shadow-popup)

Use a shadcn theme

Paste a theme of shadcn (or of a theme generator for shadcn) after the import. It sets the shadcn variables. Add these lines for the shadcn look of the highlight, the separator and the popups:

:root {
    --highlight: var(--accent);
    --highlight-foreground: var(--accent-foreground);
    --separator: var(--border);
    --popup-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1); /* shadow-md */
}

Dark mode

The theme sets the dark values with @variant dark, so it follows the dark variant of your build. Declare a custom variant before the import. The variant must match the <html> element itself, because the theme sets the variables on :root:

@import "tailwindcss";
@custom-variant dark (&:where(.dark, .dark *));
@import "../../vendor/phem/ui-base/assets/theme.css";

The default variant of Tailwind (the prefers-color-scheme media query) also works. The variant of shadcn, &:is(.dark *), does not match <html>: a shadcn theme sets its own dark values in .dark { … }, but the dark values of the variables of phem/ui-base do not apply.

Add classes

Each part merges the className of the caller into its classes. Turn on the Tailwind merger of phem, so that a class of the caller replaces a class of the same group (see phem/docs/styling.md):

<Button className="h-9 px-4">Save</Button>
# config/packages/phem.yaml
phem:
    class_merger:
        tailwind:
            css: '%kernel.project_dir%/assets/styles/app.css'

Set the css option to the entry that imports the theme. The merger then reads the @theme blocks of the theme file too, so it knows rounded-control, rounded-popup and shadow-popup. Without the css option, these names are in no group: <Button className="rounded-md"> keeps rounded-control too, and the CSS order picks the radius.

Names

The Base UI X.Root is the X tag, and each other part is X<Part>: Dialog, DialogTrigger, DialogPopup, DialogTitle… A root that shares its props with its parts is a class with #[Provide] (import it with use). The parts are function components (import them with use function). A part that shares its props with the parts in it is also a class: AccordionItem and MenuRadioGroup.

  • Portal and Positioner: they have no tag. A popup goes in the top layer (popover="manual", or a native <dialog>), and the Positioner props (side, align, sideOffset…) are props of the root.
  • Backdrop: the ::backdrop of the native <dialog>, styled by the popup classes.
  • Ids: parts take their ids from a value (or the id of the root), because the morph needs ids from the server render.

Use it with a coding agent

The package ships its examples (examples/, the extra.phem.examples key of composer.json) and this guide (extra.phem.guide) for the coding agents. In an app, phemc gives them to the agent (see phem/docs/ai-agents.md):

vendor/bin/phemc components                  # the families, one line each
vendor/bin/phemc components Dialog           # the props, the context and the anatomy of a component
vendor/bin/phemc examples Dialog             # the examples that use Dialog
vendor/bin/phemc search "dialog with a form" # the best components and examples for a task

Follow these rules when you write code with the components:

  • Families: a family is one file of src/ (Dialog.phem): its root and its parts. Import the root and the class parts with use, and the function parts with use function, as phemc components <name> shows.
  • Anatomy: a part goes inside the component of its context, as the anatomy of the root shows. A popup part goes inside its root, and the root has the Positioner props.
  • Start from an example: each example is one use case of base-ui.com, with the text of its page. Copy the closest one, and keep its classes, its handle and its data attributes.
  • Check: run vendor/bin/phemc check <file> after each change.

Status

All 37 Base UI components are here. The parts follow the Base UI anatomy, with this exception:

  • Switch: the root is SwitchRoot, because switch is a reserved word in PHP.

Develop

The bundle requires the phem/phem release from Packagist. The commands run in the images of compose.yaml (the dev and e2e services, from docker/). They use vendor/bin/phemc, the phemc binary of the installed phem release. A component that needs a new behavior of phem waits for the phem release that has it.

The components use only the public API of phem: the components, the controllers and their documented attributes. A package of an app can do the same.

The demos of the gallery are the examples of the package (examples/, namespace Phem\Ui\Base\Examples). A demo page (demo/src/Ui/Demos/) shows them, and the demo compiles them with phemc build src --examples-of phem/ui-base. Give each example a docblock: its title, then the text of its section on base-ui.com. make check checks the examples and runs the retrieval eval of the search (tests/retrieval.yaml).

make install     # composer install
make test        # PHPUnit render tests
make check       # phemc check of the components and the examples, and the retrieval eval
make demo        # the gallery on http://localhost:8100 (FrankenPHP, production image)
make demo-watch  # the same gallery in the dev environment, restarted after each change
make test-e2e    # the browser tests of the demo (Playwright PHP)

The demo runs in its own production image (demo/etc/Dockerfile, with its Caddyfile and PHP settings): FrankenPHP in worker mode, APP_ENV=prod. The build context is the root of the repository, because the demo installs phem/ui-base from it (a Composer path repository). Rebuild the image after each change (make demo does it). The image copies demo/.env.local (not in git) with the APP_SECRET of the demo. make demo writes it with a random secret when it is missing. To build and run the image without make:

docker build -f demo/etc/Dockerfile -t phem-ui-base-demo .
docker run --rm -p 8080:8080 phem-ui-base-demo

While you work on a component or a controller, run make demo-watch. It serves the same gallery on http://localhost:8100 with the watch stage of demo/etc/Dockerfile: FrankenPHP in worker mode, APP_ENV=dev, on a bind mount of the repository. The image is built only once, and demo/etc/watch reloads the demo after each change:

  • .phem files (the demo and the components): phemc watch rebuilds them and restarts FrankenPHP
  • PHP classes and config files (the demo and the components): the watch options of the worker restart the workers
  • Controllers and CSS (assets/): AssetMapper serves the new file on the next request, and tailwind:build --watch rebuilds the CSS

Stop make demo first: both use port 8100.

The browser tests (demo/tests/) run in the e2e image (docker/e2e.Dockerfile), with Chromium. They need no web server: the Playwright Symfony bundle sends the requests of the browser to the kernel of the demo, in the PHPUnit process. A failed test saves a screenshot and the HTML of the page in demo/var/failures/.