Flowbite Bundle Laravel Package

Getting Started

First, calibrate expectations. Despite the bundle suffix and the fact that it will show up in a Laravel-adjacent search, this is a Symfony form theme — a set of Twig blocks that map the Symfony Form component's rendering hooks (form_row, choice_widget, checkbox_widget, form_errors, …) onto Flowbite's Tailwind markup. There is no service provider, no Blade views, no Laravel integration. The realistic starting points are:

1. You are on Symfony 6.4+ / PHP 8.1+ and want Flowbite-styled forms with zero hand-written markup. This is the intended path.
2. You are on Laravel and want the look. In that case you are not really installing a package — you are lifting the Twig templates and their class maps and re-expressing them as Blade components (<x-form.input>, <x-form.select>, <x-form.error>). Budget a day; the templates are small and readable.

For path 1, the minimal sequence:

composer require tales-from-a-dev/flowbite-bundle

Then register the theme — either globally in config/packages/twig.yaml:

twig:
    form_themes: ['@Flowbite/form/flowbite_layout.html.twig']

…or per-form with {% form_theme form '@Flowbite/…' %}.

Flowbite is >= 4.0 and expects Tailwind present. Add the Flowbite Tailwind plugin and the JS bundle, or the classes render but nothing behaves.

First use case: take one existing ContactType, render it with plain form_start/form_row/form_end, and diff the HTML. That diff is your entire mental model of the bundle. Then read docs/theme_customization.md — the class-override configuration and the "class block list" are the actual public API surface.

Implementation Patterns

Theme layering. Treat the bundle theme as a base and your own theme as a child:

{% use '@Flowbite/form/flowbite_layout.html.twig' %}
{% block form_row %} … {% endblock %}

Register your theme after the bundle's in form_themes so the more specific blocks win. This is how you adjust one widget without forking anything.

Class overrides over template overrides. The documented customization path (overriding CSS classes, class block list) exists precisely so you don't copy templates. Prefer config-level class maps; you get upgrade safety when Flowbite bumps a major version and markup changes.

Wrap forms deliberately. Flowbite's spacing model assumes a vertical stack with mb-5/space-y-* on the row wrapper. If you compose multi-column forms, override form_row once and control the grid from your layout, rather than sprinkling attr.class on every field.

Compound fields are the weak spot. EntityType, ChoiceType with many options, and DateType render as native <select>/<input>. Flowbite's custom select/datepicker need JS init — initFlowbite() after DOM ready, or per-component constructors. For anything beyond a handful of options, wire TomSelect or a Symfony UX component instead of fighting the theme.

Hotwire/Turbo/LiveComponent reality. Every partial re-render produces fresh DOM that Flowbite has not seen. Put initFlowbite() behind a turbo:load / live:render listener, or you get dead dropdowns and un-styled selects on the second interaction.

Mapping to Laravel. The Twig blocks translate almost 1:1 to Blade components, and that is the sane port. Keep the class strings in a PHP array or config file rather than inline, so you can swap Flowbite versions in one place — mirroring the bundle's own class-map design.

Gotchas and Tips

• The Laravel mismatch is the headline caveat. No dependents, 90 stars, Symfony-only. If your app is Laravel, you are reading templates for inspiration, not installing a dependency. Do not add it to composer.json expecting it to do anything.
• Twig is required by the bundle's design; Laravel ships Blade. Any port is a rewrite, not a shim.
• Tailwind will purge your classes. Flowbite classes must appear in files scanned by content. Class strings assembled at runtime (or built in PHP and echoed) disappear in production builds. Safelist them.
• Flowbite 3 → 4 markup differs. The bundle pins >= 4.0; pasting older Flowbite snippets into an overridden block will look subtly broken. Check the vendored template, not a blog post.
• Missing error/help blocks are silent. If form_errors or form_help isn't wired through your override, validation messages simply don't render. Test a deliberately invalid submission early.
• attr merging can clobber theme classes depending on where you pass attr: {class: …}. Use attr for additions, overrides for replacements.
• Accessibility depends on id/for pairing. label: false or custom label rendering breaks the Flowbite label association and the peer-based styling.
• Debugging which block wins: use bin/console debug:twig and the form profiler panel. Most "my override does nothing" bugs are theme ordering, not block naming.
• Treat the templates as the docs. The docs/ folder covers getting started and customization, but block names, exact class maps, and the _form_errors/form_help contract live in the Twig files. Open them before guessing.
• Pin the version. With a small team and infrequent releases, an unexpected Flowbite major bump is the likeliest breakage vector.