Headless Concept & Customization

BreezeUI deeply integrates the Headless UI concept into its design. While we provide out-of-the-box, beautiful default styles, you still have an extremely high degree of freedom to customize your components.

What is the Headless Concept?

The core of the Headless concept is completely decoupling the interactive logic of a component from its visual styling.

In BreezeUI, complex interactive components (like Dialog, Dropdown Menu, Select, etc.) are built on top of Radix Vue. This means:

• Accessibility (A11y): Components follow WAI-ARIA standards by default, supporting keyboard navigation, screen readers, etc.
• State Management: Complex focus management, popover z-index management, click-outside-to-close, and other logic are handled under the hood.
• Style Freedom: The underlying logic contains absolutely no CSS. BreezeUI simply applies a layer of default styles based on Tailwind CSS on top of it.

How to Customize Styles?

BreezeUI provides multiple levels of style customization to meet different needs.

1. Class Override

This is the most direct and commonly used customization method. All BreezeUI components support passing the class attribute directly, and internally use tailwind-merge to intelligently merge class names.

This means you can directly pass Tailwind CSS classes to override the default styles without worrying about CSS specificity issues.

<template>
  <!-- Default Button -->
  <BrButton>Default Button</BrButton>

  <!-- Override background and text color -->
  <BrButton class="bg-purple-500 hover:bg-purple-600 text-white">
    Purple Button
  </BrButton>

  <!-- Modify padding and border radius -->
  <BrButton class="px-8 py-4 rounded-3xl">
    Large Radius Button
  </BrButton>
</template>

2. Theming Variables

If you need to globally change the color scheme of the component library (e.g., modifying the primary color, border radius, background color, etc.), it is recommended to use CSS variables or BrConfigProvider for global theme configuration.

This approach is highly suitable for implementing Dark Mode or Multiple Themes.

For detailed instructions, please refer to the Theming documentation.

3. Slots & Polymorphism

In addition to modifying CSS, you can completely change the internal DOM structure of a component through Vue Slots. BreezeUI exposes a rich set of slots for you to insert custom content.

Furthermore, some components (like Button) support the as attribute (polymorphism), allowing you to change the rendered HTML tag, such as rendering a button as an a tag or router-link, thereby extending functionality while maintaining the original style and behavior.

<template>
  <BrButton as="a" href="https://github.com" target="_blank">
    This is a link
  </BrButton>
</template>

Summary

BreezeUI provides you with beautiful default appearances based on Tailwind CSS, while retaining the powerful extensibility of Headless UI. You can easily build user interfaces that perfectly match your design specifications, just like building blocks.