- How do I install Overlook in a Laravel Filament panel?
- Run composer require awcodes/overlook, then register OverlookPlugin::make() in your panel's plugins() array and add OverlookWidget::class to the widgets() array in the same panel provider. If you do not already have a custom Filament theme, create one first, then add the plugin's Blade views to your theme CSS with @source '../../../../vendor/awcodes/overlook/resources/**/*.blade.php' and rebuild your assets. No migrations, queues, or other infrastructure changes are required.
- Which Filament versions does awcodes/overlook support?
- Compatibility is strictly one plugin major per Filament major: 1.x for Filament 2.x, 2.x for Filament 3.x, 3.x for Filament 4.x, and 4.x for Filament 4.x and 5.x. There is no cross-major tolerance, so each Filament major upgrade should be paired with the matching plugin major upgrade. Pin both packages in composer.json and check the compatibility matrix before upgrading.
- Why does the Overlook widget look unstyled or missing styles?
- Overlook ships Blade views that Filament's Tailwind build must scan, so the panel needs a custom theme. Add @source '../../../../vendor/awcodes/overlook/resources/**/*.blade.php' to your theme CSS file and rebuild your assets. Without a custom theme and a rebuilt asset bundle, the widget markup renders but its styles are not generated.
- How do I include or exclude resources from the Overlook widget?
- By default Overlook displays counts for every resource registered with the Filament panel. Use the includes() or excludes() methods on OverlookPlugin to whitelist or blacklist specific resource classes. The two methods are mutually exclusive, so choose one approach per panel.
- How do I change the widget sort order or column layout in Overlook?
- Call sort() on OverlookPlugin to set the widget's position, and columns() to define how many items render per breakpoint. The columns array accepts keys such as default, sm, md, lg, xl, and 2xl, with null meaning no fixed column count at that breakpoint. The configuration is fluent and lives entirely in your panel provider.
- Will Overlook slow down my Filament dashboard with many resources?
- The widget runs an aggregate count query for each registered resource on every render, so 30 resources means 30 COUNT queries per dashboard hit per user. On large tables, or when the dashboard is the post-login landing page, that cost adds up and the package does not cache or otherwise mitigate it. Trim the resource list with includes or excludes, or cache counts yourself if the load matters.
- Are Overlook counts scoped to the current user's permissions or tenant?
- Not automatically. Counts derive from each resource's getEloquentQuery(), which is not inherently policy-scoped, so multi-tenant or policy-restricted panels can show totals the user cannot actually access. Implement the CustomizeOverlookWidget contract or use the HandlesOverlookWidgetCustomization trait and override getOverlookWidgetQuery() to apply tenancy or authorization scopes explicitly.
- How do I customize the title or query for a single resource's Overlook count?
- Implement the CustomizeOverlookWidget contract on the resource, or apply the HandlesOverlookWidgetCustomization trait and override getOverlookWidgetTitle() and getOverlookWidgetQuery(). These methods let you rename the item and constrain or reshape the underlying query per resource. The extension surface is idiomatic Filament and follows the same pattern as other resource-level customizations.
- Does Overlook require the PHP intl extension for abbreviated counts?
- Since v1.2.0, abbreviated counts are formatted with NumberFormatter, which requires ext-intl. Make sure the extension is available in local, CI, and production environments if you enable abbreviateCount(). Without it, abbreviated formatting will not work as expected.
- How do I exclude soft-deleted records from Overlook counts?
- Soft-delete exclusion is opt-in, so call withoutTrashed() on OverlookPlugin if you want counts to ignore trashed rows. This behavior was corrected in 3.0.3, so pin at least that patch release if it matters to you. Without the call, counts follow the resource's default query, which may include soft-deleted records depending on your model setup.