Selia UI Documentation

Selia is an opinionated UI library for React built on top of Tailwind CSS and Base UI. It is designed to be used either as a ready-to-use component library or as a foundation for building a custom design system.

Key characteristics include:

• Opinionated Defaults: Components come with intentional spacing, colors, and visual balance to reduce the need for manual utility class overrides.
• Contextual Styling: Instead of per-usage overrides, Selia uses contextual styling to handle common component combinations automatically.
• Customizable: While opinionated by default, it is designed to be highly adjustable to fit specific design needs.

The Selia Laravel integration provides a comprehensive set of features out of the box:

• Identity & Access: Authentication, Roles and permissions, User list management, Role list management, Permission list management.
• User Management: Password reset, Email verification, Update profile, Delete profile.
• UI/UX: Dark mode support, Multiple language support (via mcamara/laravel-localization and i18next).
• Database: SQLite by default, but configurable to MySQL or PostgreSQL.

Selia components are designed to work together out of the box using two primary mechanisms: Plain Variants and Contextual Styling.

1. Plain Variants: Many components provide a variant="plain" prop. This strips away default visual styling like backgrounds, borders, and shadows, making the component suitable for nesting inside other components without visual conflicts.
2. Contextual Styling: Parent components use data-slot attributes to apply specific styles to their children. This allows a parent (like a Card or Command) to automatically adjust the appearance of nested components (like a TableContainer or InputGroup) to ensure a cohesive layout.

The AlertDialog follows a specific composition pattern. It requires an AlertDialogTrigger to open the dialog and an AlertDialogPopup to contain the content. The content is organized into Header (containing a Title), Body (containing a Description), and Footer (containing a Close action).

<AlertDialog>
  <AlertDialogTrigger>
    Trigger
  </AlertDialogTrigger>
  <AlertDialogPopup>
    <AlertDialogHeader>
      <AlertDialogTitle>
        Title
      </AlertDialogTitle>
    </AlertDialogHeader>
    <AlertDialogBody>
      <AlertDialogDescription>
        Description
      </AlertDialogDescription>
    </AlertDialogBody>
    <AlertDialogFooter>
      <AlertDialogClose>
        Close
      </AlertDialogClose>
    </AlertDialogFooter>
  </AlertDialogPopup>
</AlertDialog>

The Menu component follows a composition pattern where a Menu root wraps a MenuTrigger (the button that opens the menu) and a MenuPopup (the container for the actual options). Inside the MenuPopup, you can organize items using MenuGroup, MenuSeparator, or create hierarchies using MenuSubmenu.

<Menu>
  <MenuTrigger>Menu</MenuTrigger>
  <MenuPopup>
    <MenuGroup>
      <MenuGroupLabel>Account</MenuGroupLabel>
      <MenuItem>
        <UserIcon />
        Profile
      </MenuItem>
    </MenuGroup>
    <MenuSeparator />
    <MenuSubmenu>
      <MenuSubmenuTrigger>Theme</MenuSubmenuTrigger>
      <MenuPopup>
        <MenuItem>Light</MenuItem>
        <MenuItem>Dark</MenuItem>
      </MenuPopup>
    </MenuSubmenu>
  </MenuPopup>
</Menu>

A Dialog is composed of a root Dialog component containing a DialogTrigger (to open the modal) and a DialogPopup (the modal content container). The popup typically follows a structured layout of Header, Body, and Footer.

<Dialog>
  <DialogTrigger>Open Dialog</DialogTrigger>
  <DialogPopup>
    <DialogHeader>
      <DialogTitle>Dialog Title</DialogTitle>
    </DialogHeader>
    <DialogBody>
      <DialogDescription>Dialog Description</DialogDescription>
    </DialogBody>
    <DialogFooter>
      <DialogClose>Close</DialogClose>
    </DialogFooter>
  </DialogPopup>
</Dialog>

The Meter component provides visual indicators for showing numeric values within a specific range.

When to use Meter vs. Progress:

• Use Meter when displaying static numeric values in a range (e.g., storage capacity, battery level).
• Use Progress when showing the progress of an active task in a horizontal bar.

Use the direction prop on DrawerPopup to specify which edge the drawer slides in from. The default is right.

Important: To ensure swipe-to-dismiss works correctly, the swipeDirection prop on the Drawer component must match the direction prop on the DrawerPopup.

// Example: Left-side drawer
<Drawer swipeDirection="left">
  <DrawerPopup direction="left">...</DrawerPopup>
</Drawer>

// Other valid directions: "right", "top", "bottom"

Unlike traditional UI libraries that are consumed as closed, opaque packages, Selia is designed for code ownership.

When you use a Selia component, the source code is intended to become part of your own codebase. This allows you to:

• Read and Understand: No hidden abstraction layers.
• Modify and Refactor: Change the component logic or styles directly to suit your application.
• Remove: Delete components that are no longer needed without managing complex dependency trees.

This approach aims to prevent dependency lock-in and provides full control over your UI evolution.