cmdinglasan/filament-boring-avatars
A Filament plugin that generates deterministic Boring Avatars for users and models, with configurable variants, colors, and sizes. Add privacy-friendly, consistent SVG avatars to tables, forms, and infolists without relying on external image services.
Install
composer require cmdinglasan/filament-boring-avatars
The package wraps the Boring Avatars SVG generator so a Filament panel can render a deterministic avatar from any string (name, email, username) instead of a static placeholder or an uploaded file. If you are on v1.0.0 already, composer update cmdinglasan/filament-boring-avatars gets you the v1.2 fixes — see Gotchas for the dependency-collision change.
Where to look first
PanelProvider::panel()->plugins([...]) or is auto-discovered.resources/views in the package — the Blade template is the real contract; publishing it is how you customise output.First use case
Swap the default user avatar on a UserResource table for a generated one, seeded by email so the same user always gets the same image:
// UserResource::table()
Tables\Columns\TextColumn::make('name')
->label('User')
->description(fn (User $record) => $record->email)
// avatar column/entry component from the package, seeded by email
Do this in one place first (a single resource), confirm it renders inside your panel’s CSP and theme, then roll it out. Because output is deterministic, nothing about rolling it out later changes existing avatars.
Determinism is the feature — pick one seed and standardise on it. The avatar is a pure function of (seed, variant, colors, size). Choose email or uuid as the seed and never mix: if some resources seed by name and others by email, the same user gets two different avatars across the app, which looks like a bug to end users. Seed by email (stable, unique) and document it.
As a table column. This is the highest-value integration — dense lists of people (members, comment authors, audit trails) stop looking anonymous. Pair it with ->circular() and a fixed size so row heights stay uniform.
As an infolist entry on the view/edit page. Puts a recognisable face next to the record title in the header, mirroring what the table shows.
As a form placeholder. A read-only avatar in the user form (generated from the email field as it is typed) gives immediate feedback on which avatar a new user will get — useful when onboarding or importing users.
In plain Blade. For anything outside the panel (emails, PDFs, public pages), use the underlying Blade component directly rather than building a resource. Keep the same seed and palette so avatars match the panel.
Keep the variant/palette in config, not in call sites. Centralise variant (marble, beam, pixel, sunset, ring, bauhaus) and the colour array in one config file or a small helper. The colours array is positional — reordering it changes every avatar, so scattering palettes across resources means a brand tweak becomes a find-and-replace.
Model trait. The release corrects the package’s trait (PR #3) — the intended pattern is a trait on your User (or any model) exposing the avatar URL/seed, so $user->avatar works in Blade, notifications and API resources without repeating the seed logic. If you had copied the trait’s body into a base model to work around the earlier bug, delete the copy and use the shipped trait so future fixes reach you.
Integration tip: these are inline SVGs generated by the Boring Avatars JS library, so treat them as UI decoration — wrap them with aria-hidden or an empty alt when the user’s name is already adjacent in the DOM, to avoid screen readers announcing the same person twice.
The dependency-collision fix is the real content of this release. PRs #12/#13 (“Fix issue on dependency collision”) address the classic Filament-plugin failure where the package’s composer.json constraints clash with a Filament or Laravel version you already have, and Composer refuses to install or silently downgrades something else. If you bounced off v1.0.0 with an unresolvable dependency graph, retry now. After updating, diff composer.lock — specifically watch for Filament moving backwards.
No breaking API changes v1.0.0 → v1.2. The remaining PRs are docs, a trait correction, and Dependabot bumps of CI actions (fetch-metadata, laravel-pint-action, ramsey/composer-install), not runtime dependencies. You do not need to read those changelog lines as behaviour changes to your app. Note that the dependabot lines tell you the maintainers’ CI is green but not much about runtime quality — the package is small and single-maintainer, so read the Blade template rather than trusting the version number.
Verify the trait signature after upgrading. PR #3 (“corrected trait”) means the trait’s public method changed. If you pinned it via use …Trait; and overrode a method, check the override still lines up; a corrected trait can quietly break a parent:: call.
Determinism cuts both ways. The same seed with the same config always produces the same avatar — excellent for caching, but it also means a user cannot “regenerate” their avatar. There is no random() escape hatch worth using, since randomising the seed defeats the identity purpose. If users must be able to change it, persist a avatar_seed column and seed from that, defaulting to the email.
Colour and dark mode. Boring Avatars palettes are baked into the SVG, so they do not follow Filament’s light/dark toggle. Palettes tuned for a light panel can look washed out in dark mode. Either pick mid-tone palettes that survive both, or publish the view and inject panel-aware colours, accepting that the same user’s avatar then differs between themes.
CSP and asset loading. If the generator is the JS library, check your Content-Security-Policy allows it (and that it is bundled rather than CDN-loaded if you run airgapped or behind strict CSP). Nothing renders — or worse, a blank element with a reserved height appears — when the script is blocked.
Debugging checklist when an avatar looks wrong: (1) is the seed actually the string you think it is (a null email → one shared avatar for every user, a common silent failure on imported accounts)? (2) did the palette array get reordered? (3) is the variant inherited from config in one place and hard-coded in another? (4) is the SVG being stripped by an HTML sanitiser or a Blade {{ }} vs {!! !!} mistake?
Extension point. Publish the package’s views/config (php artisan vendor:publish --tag=…, per the README) and override the template rather than forking. That is the difference between picking up the next fix release cleanly and owning a fork permanently.
How can I help you explore Laravel packages today?