- How do I install and register the focal point picker in a Filament panel?
- Install it with Composer using the johncarter/filament-focal-point-picker package name, then register the plugin in the relevant PanelProvider. After that you add the field to a resource or form schema and add a cast or accessor on the owning model for the stored coordinates. For a developer already comfortable with Filament, expect a few hours rather than days. It is a Filament form-field plugin, so there is nothing useful to install if you are not running a Filament panel.
- Which Filament and Laravel versions does this package support?
- Check the composer.json constraints before committing, because Filament ships breaking majors roughly once a year and a field package must be re-released for each one. The package is a Filament v3-era plugin and a stated commitment to v4 support is not confirmed, so verify the constraint against your panel version. Filament v3 to v4 included namespace, asset, and Tailwind-generation changes that commonly break third-party fields. Pin your Filament version until you have tested the field on your stack.
- How is the focal point stored on the model, and how do I read it?
- The persisted payload is deliberately small: typically a pair of percentages for x and y, or a compact JSON blob on the owning model. The package captures the intent and stops at persistence, so the accessor contract is effectively yours to define. Decide between two discrete columns and a JSON column early, since that choice drives migration ergonomics and how easily you can query or backfill values. Default existing rows to center (50/50) so nothing changes visually before and after the install.
- Does the package apply the focal point to rendered images, or do I have to?
- Assume you own the rendering. The plugin captures and stores focal coordinates but does not output crops, so consuming the value on the front end via object-position, per-conversion focal cropping, or responsive variants is your work. Budget for that gap explicitly: it is the difference between a one-day install and a two-week feature. If your images flow through a transformation layer such as Glide, imgix, or Spatie conversions, confirm the focal point can be applied per variant, otherwise editors will tune a value that only affects the original image.
- Does it work with Spatie Media Library conversions?
- This is unverified and it is one of the seams worth testing before you commit. The field may expect a single original-image URL rather than a Media Library conversion pipeline, which changes how you wire the stored coordinates into each generated variant. If your conversions are driven by Spatie, plan on custom conversion code that reads the focal point and passes it to your image driver. Validate it on one resource with real assets before rolling it out.
- Does the picker work inside repeaters, builders, and relation managers?
- Nested form state is unverified, and it is exactly where Filament field packages most often break. Top-level fields on a resource form are the safe, well-trodden path; repeaters, builders, and relation managers introduce state paths the interactive Alpine component may not resolve correctly. Test the specific nested container you need before designing a content model around it. If nesting fails, you can still use the field at the top level and manage per-image focal points through a related record.
- Do I need to compile assets, and will it break under a strict CSP?
- The interactive picking behavior is client-side Alpine and Livewire, with assets registered through Filament's asset pipeline. Confirm whether the JS and CSS are precompiled and published through FilamentAsset or whether a host-side build step is required, since unversioned or unpublished assets cause 404s in production builds. Under a strict Content Security Policy, check that no inline scripts are required and that assets load from an allowed origin. Also verify the focal point survives Livewire re-renders rather than silently resetting to center.
- How do I test a Filament form that uses the focal point picker?
- Test the parts you control: that the field mounts in your resource form, that the coordinates round-trip through your cast or accessor, and that your front-end rendering applies object-position from the stored value. Livewire component tests can assert the field's state after a fill, and a feature test can confirm the value persists on save. Add a rendering test that snapshots the generated markup for a known focal point so regressions in your cropping code are caught. Because the package stops at persistence, most of your test surface is your own consumption code.
- Is it safe to depend on a package with one maintainer and 44 stars?
- The dominant risk here is governance rather than code quality. Single maintainer, 44 stars, zero dependents, and MIT licensing means no downstream validation and no commercial support, so the maintainer's release cadence is effectively your availability SLA for each new Filament major. Check the actual commit and issue-response history over the last 12 months rather than trusting the release tag date. Treat it as a commodity utility you could replace or vendor, not a strategic dependency, and be ready to fork it if Filament ships a breaking major.
- How do I migrate from an existing cropper, or should I build this myself?
- Run the two side by side behind a feature flag and cut over per resource type rather than globally, because the failure surface is larger than it looks. Backfill focal points deliberately instead of implicitly, and keep any existing crop data intact until the new rendering path is proven. If you are not on Filament, the field is unusable and the Alpine picking logic is trivially extractable, so building it yourself may be the cheaper route. Because the package ends at persistence, weigh whether a small custom field plus your own cropping code gives you more control than adopting this dependency.