Docs
Introduction

Introduction

Understand Flexilla's mental model before you start building with it.

Flexilla is a headless, framework-agnostic library for interactive UI components such as accordions, tabs, dropdowns, modals, tooltips, and more.

Headless means Flexilla gives you behavior, state management, and accessibility-oriented wiring, while you stay in control of the markup and styling.

The mental model

When you use Flexilla, there are three parts working together:

Your HTML structure
Flexilla’s JavaScript behavior
Your CSS or utility classes reacting to state

Flexilla does not try to own your design system. Instead, it updates attributes such as:

data-state
aria-expanded
component-specific data-* attributes

You then use those attributes to style the component however you want.

What Flexilla gives you

interaction logic for common UI patterns
state updates through data-* attributes
keyboard and accessibility-friendly behavior for supported components
framework-agnostic usage for server-rendered and vanilla projects

What you provide

the HTML markup
the classes and visual design
the selectors used for initialization
any custom animations or transitions

A simple example of the pattern

If Flexilla changes an element from data-state="close" to data-state="open", your CSS can respond immediately:

[data-state="close"] {
  display: none;
}

[data-state="open"] {
  display: block;
}

That same pattern works with plain CSS, UnoCSS, or Tailwind CSS.

Choose the right entry point

Use @flexilla/flexilla if you want one package for multiple components.
Use individual packages such as @flexilla/accordion or @flexilla/modal if you only need a few pieces.
Use lower-level packages when you want more advanced composition later.

Manual init vs auto init

Flexilla supports both patterns:

manual initialization when you want explicit control
autoInit() when you want Flexilla to find matching elements on the page

Manual init example:

import { Accordion } from "@flexilla/accordion";

new Accordion("#faq");

Auto init example:

import { Accordion } from "@flexilla/accordion";

Accordion.autoInit();

Best fit for Flexilla

Flexilla is especially useful when:

you are not using a heavy UI framework
you want interactive components in server-rendered pages
you want to keep full control over styling
you are working in Astro, Laravel, Symfony, Vue, static sites, or similar environments

Before you jump into components

There are two important things to remember:

Flexilla components still need the correct HTML structure and attributes.
Because Flexilla is headless, a component may be functional before it looks complete.

That is expected. Behavior comes from Flexilla, presentation comes from you.

FAQ

Are Flexilla components accessible?

They are designed with accessibility-oriented behavior in mind, but you should still use proper semantic markup and test the final experience in your own UI.

Can I use Flexilla in production?

Yes. Flexilla is intended for real projects, especially where you want interactive behavior without giving up control of styling and markup.

Do I need Tailwind or UnoCSS?

No. Flexilla works with plain CSS too. Tailwind and UnoCSS simply make state-based styling more convenient.

Can I use Flexilla with framework-based apps?

Yes, especially in projects where you still want DOM-first, headless component behavior. The fit is strongest in environments where HTML and progressive enhancement are important.

Next Page Installation