Html Theme

Bootstrap themes for the UI Awesome component ecosystem.
Application-scoped recipes for Bootstrap 5.3 and Bootstrap 6.0.0-alpha.1.

Features

Installation

composer require ui-awesome/html-theme:^0.1

Quick start

A theme resolves configuration recipes for semantic component contexts. Pass it to components through an application-scoped Config, and describe each component with a ComponentContext. The examples name components, variants, and states with the UIAwesome\Html\Core\Component\Values enums; plain strings such as 'alert' or 'dismissible' remain accepted.

Bootstrap 5

use UIAwesome\Html\Core\Component\Alert;
use UIAwesome\Html\Core\Component\Values\{ComponentName, ComponentState};
use UIAwesome\Html\Core\Config\{ComponentContext, Config};
use UIAwesome\Html\Theme\Bootstrap5;

$config = new Config(theme: new Bootstrap5());

echo Alert::tag()
    ->config($config, new ComponentContext(ComponentName::ALERT, variant: 'success'))
    ->content('Your changes have been saved.')
    ->id('alert-saved')
    ->render();

States refine a variant. The dismissible state adds the Bootstrap close button:

echo Alert::tag()
    ->config(
        $config,
        new ComponentContext(ComponentName::ALERT, variant: 'danger', states: [ComponentState::DISMISSIBLE]),
    )
    ->content('Your session expired.')
    ->id('alert-session')
    ->render();

Bootstrap 6 alpha

Bootstrap6 targets Bootstrap 6.0.0-alpha.1. Support is experimental and tied to that alpha, not to a stable Bootstrap 6 release.

The navbar context renders a Bootstrap 6 navigation bar. The menu marks the item that matches the current path as active and styles disabled items.

use UIAwesome\Html\Core\Component\{Item, Menu, NavBar};
use UIAwesome\Html\Theme\Bootstrap6;

$config = new Config(theme: new Bootstrap6());

echo NavBar::tag()
    ->config($config, new ComponentContext(ComponentName::NAVBAR))
    ->brandLink('/')
    ->brandText('UI Awesome')
    ->menu(
        Menu::tag()
            ->currentPath('/docs')
            ->id('main-menu')
            ->items(
                Item::tag()->label('Home')->link('/'),
                Item::tag()->label('Docs')->link('/docs'),
                Item::tag()->label('Pricing')->link('/pricing'),
                Item::tag()->label('Enterprise')->link('/enterprise')->disabled(),
            ),
    )
    ->render();

Navbar dropdown

A Dropdown nested in the navbar menu receives the theme's dropdown toggle. toggleLabel() replaces only the toggle text and keeps its classes and data attributes.

use UIAwesome\Html\Core\Component\Dropdown;

echo NavBar::tag()
    ->config($config, new ComponentContext(ComponentName::NAVBAR))
    ->brandLink('/')
    ->brandText('UI Awesome')
    ->menu(
        Menu::tag()
            ->id('main-menu')
            ->items(
                Item::tag()->label('Home')->link('/'),
                Dropdown::tag()
                    ->containerTag(false)
                    ->id(null)
                    ->toggleLabel('Docs')
                    ->items(
                        Item::tag()->label('Guides')->link('/docs/guides'),
                        Item::tag()->label('API reference')->link('/docs/api'),
                    ),
            ),
    )
    ->render();

To build the toggle yourself, the menu-dropdown toggle recipe applies the same styling without content, and the dropdown keeps a toggle set through toggle():

use UIAwesome\Html\Core\Component\Toggle;
use UIAwesome\Html\Core\Component\Values\ToggleVariant;

$toggle = Toggle::tag()
    ->config($config, new ComponentContext(ComponentName::TOGGLE, variant: ToggleVariant::MENU_DROPDOWN))
    ->content('Docs');

Form fields

ui-awesome/html-field uses the same configuration to theme the field and its control, label, hint, and validation feedback. $form is any UIAwesome\FormModel\FormModelInterface implementation.

use UIAwesome\Html\Field\Field;

echo Field::tag()
    ->config($config)
    ->formModel($form)
    ->property('email')
    ->control('email')
    ->render();

Theme selector

The selector-theme toggle renders a button with a moon icon (theme-dark-icon) and a sun icon (theme-light-icon), both hidden with d-none. The package ships no JavaScript, so the application switches the color mode.

use UIAwesome\Html\Core\Component\Toggle;
use UIAwesome\Html\Core\Component\Values\ToggleVariant;

echo Toggle::tag()
    ->config($config, new ComponentContext(ComponentName::TOGGLE, variant: ToggleVariant::SELECTOR_THEME))
    ->id('theme-selector')
    ->render();

Bootstrap 5.3 and Bootstrap 6 alpha both read the color mode from the data-bs-theme attribute. This example script toggles it on <html>, shows the icon for the mode the button switches to, and stores the choice in localStorage. Load it after the button, and adapt it to the application's asset pipeline.

const root = document.documentElement;
const icons = {
  dark: document.getElementById("theme-dark-icon"),
  light: document.getElementById("theme-light-icon"),
};

const apply = (theme) => {
  root.setAttribute("data-bs-theme", theme);
  icons.dark.classList.toggle("d-none", theme === "dark");
  icons.light.classList.toggle("d-none", theme === "light");
};

const preferred = matchMedia("(prefers-color-scheme: dark)").matches
  ? "dark"
  : "light";

apply(localStorage.getItem("theme") ?? preferred);

document.getElementById("theme-selector").addEventListener("click", () => {
  const theme =
    root.getAttribute("data-bs-theme") === "dark" ? "light" : "dark";

  localStorage.setItem("theme", theme);
  apply(theme);
});

Supported contexts

Both themes resolve recipes for the alert, breadcrumb, dropdown, navbar, and toggle components and for the field slots (label, controls, choice containers and labels, hints, and errors). Supported variants differ by Bootstrap version: for example, Bootstrap 6 adds the accent and inverse alert variants and a neutral alert without a variant, and has no light or dark alert variants. A context the theme does not recognize yields no recipe, so the component keeps its own defaults.

Assets and compatibility

• Load the matching Bootstrap CSS and JavaScript separately in your application. This package renders markup and does not install, load, or initialize browser assets.
• Bootstrap 6 alpha uses ES modules; do not assume a window.bootstrap global or reuse Bootstrap 5 initialization.
• Bootstrap 6 navigation is static only. The core component model does not yet provide the dialog/drawer structure required for responsive Bootstrap 6 navigation; toggle.menu has no Bootstrap 6 recipe.
• The theme selector styles a control only. Switching color schemes and persisting the selection require application JavaScript; see Theme selector.

Documentation

For detailed configuration options and advanced usage.

• 🧪 Testing Guide

Package information

Project status

Our social networks

License