Advanced Controls Laravel Package

Getting Started

Install the package with Composer:

composer require allyoullneed/advanced-controls

Laravel package auto-discovery should register the Blade components automatically. Verify by rendering a known component in a scratch view:

<x-rating :value="4" disabled />

If that resolves, the package is wired up correctly.

Where to look first

The README intentionally points to the external site for component documentation, so start in two places:

1. The vendor source to see the actual component names, accepted props, and markup:

   vendor/allyoullneed/advanced-controls/resources/views/components
   

2. Any package config/service provider in vendor/allyoullneed/advanced-controls/src to find configuration keys for icon sets and chart CDN behaviour.

Do this before designing around the package. The release notes show components such as rating, select, input, checkbox, radio, toggle, tab, chart, avatar, indicator, dropdown, menuItem, pin, and toc, but the README alone does not give their full APIs.

First practical use case

Start with a small Livewire form plus a dashboard panel:

<form wire:submit="save">
    <x-input wire:model="name" label="Name" />
    <x-select wire:model="role" :options="$roles" filter />
    <x-checkbox wire:model="active" label="Active" />
    <x-rating wire:model="score" />
    <button type="submit">Save</button>
</form>

<x-tab wire:model="tab">
    <!-- tab panels -->
</x-tab>

This exercises the most valuable parts of the package: Livewire-bound form fields, error styling, a filterable select, and reactive tabs. If these work cleanly in your stack, expand into charts, menus, avatars, and indicators.

Implementation Patterns

Use it as a Livewire form layer

The package is most useful where Livewire is already doing the state management. Form fields are designed to reflect Livewire validation errors automatically, and select values are passed back to Livewire. Use standard wire:model bindings rather than manual JavaScript:

<x-select
    wire:model.live="country"
    :options="$countries"
    filter
    label="Country"
/>

The filter attribute on select is the main reason to choose this package over hand-written markup for searchable dropdowns. Combine it with wire:key when the option set changes dynamically so the component resets predictably.

Drive tabs from Livewire state

Tabs can be activated through wire:model. Treat the tab component as a controlled input rather than a purely client-side widget:

<x-tab wire:model="activeTab">
    <!-- panels -->
</x-tab>

This makes tab state bookmarkable or restorable from the server when combined with query-string properties. Test the initial render carefully: if the bound value does not match a tab, decide whether you want the first tab selected or no tab selected.

Compose menus and dropdowns from small pieces

The menu/dropdown components are intended to be composed. Use menuItem for individual entries and the title/submenu features for grouped navigation. Keep the markup close to the package examples and avoid wrapping menu items in extra divs until you have confirmed the component’s internal layout expectations.

A useful workflow is to build one “application shell” partial containing the dropdown/menu/avatar/indicator markup, then reuse it in the layout. That isolates the package’s markup quirks to one file instead of spreading them across every page.

Use indicators and avatars as a status primitive

The indicator component is effectively a badge/status overlay. The release notes show it was reordered to fix overlap, so use the package’s intended nesting rather than manually positioning a dot over an avatar. A typical pattern:

<x-indicator color="green">
    <x-avatar :src="$user->avatar_url" />
</x-indicator>

If the built-in nesting does not match your design, wrap the whole composition in your own Blade component and override only the CSS you need.

Treat charts as a dashboard convenience

Charts support configurable CDN loading and attributes such as class. The practical pattern is:

• Keep chart configuration in PHP/Livewire and pass data into the component.
• Pass class for sizing and layout.
• Configure the CDN once if your application has a strict CSP or self-hosting policy.
• Avoid rendering charts during server-side PDF generation or email rendering; they depend on client-side JavaScript.

For dashboards and internal tools this is a fast win. For public-facing, performance-sensitive pages, measure the cost of the chart runtime before adopting it broadly.

Use TOC for content pages

The toc component gained a selector attribute. Use it on documentation, blog posts, or long-form pages where headings already have stable IDs:

<x-toc selector="article h2" />

Generate heading IDs in your content pipeline—do not expect the TOC to rewrite arbitrary HTML. For Livewire-driven content, verify that the TOC refreshes or is re-rendered when the content changes.

Customize through attributes first, views second

Before overriding vendor views, try passing class and other attributes. Chart explicitly supports attribute passthrough, and other components generally accept class overrides. If you must change markup, prefer one of these approaches:

1. Wrap the package component in your own Blade component and add classes there.
2. Publish/override the vendor view only for components you cannot otherwise customize.
3. Fork the package if you need deep changes across many components.

Wrapper components are the safest day-to-day pattern because they keep upgrade diffs small.

Pin versions and read release notes before upgrading

Release notes show repeated fixes around select behaviour, Apple/touch devices, Livewire validation errors, and Alpine interactions. In practice, treat minor releases as potentially behaviour-changing for interactive components. Pin a known-good version in composer.json, upgrade deliberately, and smoke-test forms and dropdowns on desktop and mobile.

Gotchas and Tips

The documentation gap is the biggest day-to-day cost

The README does not list components, props, slots, or events. You will spend time reading vendor Blade files. Keep a local notes file mapping each component to its props and quirks. If the external site is unavailable, the vendor source is the source of truth.

Tailwind may purge the package’s classes

If the components use Tailwind utility classes, your Tailwind build must scan the package’s Blade views. Add the vendor view path to your Tailwind content configuration, or safelist the classes you rely on. Without this, components can look correct in development and broken in production after a build. Verify by running a production asset build early, not at deployment time.

Alpine/Livewire must be loaded once

Several components integrate with Livewire and Alpine. Loading Alpine twice, or initializing Livewire after the components have already rendered, causes subtle failures: dropdowns that do not open, keyboard events that do not fire, or tabs that ignore wire:model. Use the standard Livewire setup and avoid adding a second Alpine instance.

Select is the highest-risk component

Release history shows repeated select fixes: value passing to Livewire, filter behaviour, Chrome handling, Apple devices, touchscreens, aria attributes, and Livewire validation errors. If your application depends heavily on searchable selects, test:

• Desktop Chrome and Safari.
• iOS Safari and touch emulation.
• A Livewire validation error on the field.
• Dynamically changing option lists.
• Keyboard navigation and screen-reader labels.

Use wire:key around dynamic selects and re-test after every package upgrade.

Error styling depends on Livewire’s error bag

Form fields turn to an error colour when Livewire raises validation errors. If you use custom validation, a different error bag, or client-side validation, that styling may not trigger. In those cases, pass an explicit error class or wrap the field in your own error presentation.

Chart CDN and CSP

The chart component can load its runtime from a CDN. Strict Content Security Policy, offline environments, or corporate networks may block it. Configure the CDN to a self-hosted asset if necessary, and verify the chart library version is compatible with the component’s expectations. Also pass explicit dimensions via class; charts without a sized container often render at zero height.

TOC depends on your heading markup

The selector attribute only works if your headings match it and have usable IDs. If you render content from Markdown, ensure your Markdown renderer generates IDs. If content is loaded dynamically through Livewire, verify the TOC is re-rendered or refreshed.

Component names may be camelCase or kebab-case

The release notes reference <x-menuItem>. Blade component resolution is based on the vendor view filenames and aliases. If <x-menuItem> does not resolve, check the components directory for the exact registered name or use the kebab-case equivalent. Do not assume every documented tag maps directly.

Artisan/view caching issues

An older release fixed component registration for php artisan commands. If you are on an early version and see missing-component errors during view:cache, route:list, or package discovery, upgrade. After package updates, clear compiled views:

php artisan view:clear
php artisan optimize:clear

In deployment, run view:cache only after confirming all package components resolve.

Accessibility is improved but not guaranteed

Release notes mention aria attributes and keyboard-event improvements, particularly for pin. That is not the same as a WCAG audit. If accessibility is a requirement, test keyboard focus order, escape behaviour, labels, and screen-reader announcements yourself. Do not rely on the package’s defaults for compliance.

Maintenance risk is real

The package has very low adoption, zero dependents, and documentation hosted externally. For internal tools and prototypes, the time savings can justify it. For long-lived production systems, either:

• Pin the version and accept that you may need to patch vendor code yourself.
• Fork the MIT-licensed repository and maintain your fork.
• Wrap components behind your own Blade components so replacing the package later is feasible.

Prefer wrappers over direct vendor overrides

If you publish vendor views, future upgrades become manual merges. Instead, create project-level components such as resources/views/components/app/select.blade.php that wrap <x-select> and enforce your design conventions. That gives you a single place to swap implementations if the package is abandoned or a component proves unreliable.

Test on real mobile devices for interactive components

The release history specifically calls out Apple devices and touchscreens. Browser emulation is not enough for select/dropdown behaviour. Test at least one real iOS device before shipping forms that rely on select, dropdown, or pin.