Laravel Glider Laravel Package

Getting Started

Glider is a Blade component package for rendering background images — including responsive, breakpoint-aware backgrounds — without hand-rolling inline style attributes in every hero section.

Minimal path from zero to first render:

1. composer require the package, then publish its config:

   php artisan vendor:publish --tag="glider-config"
   

   (Confirm the exact publish tag against the README for your installed version — tag names have shifted between majors before.)
2. Open config/glider.php first. This is where named presets and breakpoints live, and it is the file you will actually maintain. Read it before reading the component classes.
3. Render the simplest possible component in a throwaway view to confirm assets resolve:

   <x-glider-bg src="{{ asset('images/hero.jpg') }}" />
   

4. Move to the responsive variant for anything real:

   <x-glider-bg-responsive preset="hero" :breakpoints="['sm', 'lg']" />
   

Your first genuine use case is a hero/banner section: a full-bleed image behind overlaid content, swapping source per viewport. Wrap it once in your own <x-hero> component and you will not touch Glider's API directly again.

If you use Laravel Boost (new in v4.1.0): Boost now ships a Glider guideline plus a glider-development skill. After installing/updating Boost, your AI agent has the correct component signatures on hand — including which props belong to which component, which is precisely the mistake v4.1.0 fixed in the docs. Set this up before you start generating layout code, not after.

Implementation Patterns

Preset-first, props-second. Treat config/glider.php as the API and the component attributes as selectors into it. Define hero, card, avatar presets once, then let templates stay declarative:

// config/glider.php
'presets' => [
    'hero' => [
        'sizes'      => '(min-width: 1024px) 100vw, 100vw',
        'background' => 'cover',
        'position'   => 'center',
    ],
],

<section class="relative h-[60vh]">
    <x-glider-bg-responsive preset="hero" :breakpoints="['sm', 'md', 'lg']" />
    <div class="relative z-10 ...">...</div>
</section>

Split components by intent. <x-glider-bg> is the fixed-source case; <x-glider-bg-responsive> is the breakpoint-aware case. Choose the narrowest component that does the job — it keeps the rendered markup smaller and avoids the prop-mismatch trap described below.

Own the wrapper. Because Glider components are presentational, the durable pattern is one project-local component per visual role (hero, banner, card-media) that internally picks the Glider component and preset. When you upgrade Glider or change a preset name, you edit one file instead of grepping 40 Blade templates.

Compose with your layout, not around it. Glider renders a positioned background layer. The reliable structure is: positioned wrapper → Glider component → relative z-10 content. Skip the wrapper and the background will bleed past your section bounds on nested layouts.

AI-assisted scaffolding as a first-class workflow. The glider-development skill and guideline are the intended path for generating new sections. Practically: run Boost's install/update so the artifacts are present, then prompt for layout ("hero with headline + CTA") rather than for Glider markup — let the guideline constrain the component usage. Review the diff for prop placement on the first few generations; that is where stale documentation bites.

Testing. Glider output is markup, so feature tests asserting rendered content are enough:

$this->get('/')->assertSee('hero.jpg', false);

For anything breakpoint-dependent, render the Blade component directly in a unit-style test and assert against the produced style/srcset attributes rather than the full page.

Upgrade ritual. composer update → diff the published config against the vendor default → re-run Boost's install/update command → php artisan view:clear. Do the config diff by hand; the published file is yours and re-publishing silently overwrites it.

Gotchas and Tips

preset and breakpoints do not exist on <x-glider-bg>. This is the exact documentation bug fixed in v4.1.0: README and config examples attached those attributes to the non-responsive component. Blade will not error on unknown attributes on a component — they fall through or are ignored, so you get a silently unstyled background. If a preset appears to do nothing, first check you are on <x-glider-bg-responsive>.

Re-publishing config overwrites your presets. Never run vendor:publish --force on a live app. Copy the vendor default to a scratch file and merge by hand. Keep a comment banner at the top of config/glider.php noting which keys are project-specific.

Config caching. Presets are read at render time from cached config in production. Changing breakpoints and seeing no effect means you skipped php artisan config:cache (or config:clear). Same class of bug as any other config-driven package, but layout changes make it look like a CSS problem.

Breakpoint keys must match the config exactly. Unknown keys in the breakpoints array typically resolve to nothing rather than throwing — you get a partially responsive background that looks fine on desktop and wrong on mobile. Keep the set of valid keys in one place; consider a project constant or enum so templates cannot drift.

Boost artifacts are generated, not source. The guideline and glider-development skill installed into your app are managed files. Hand-editing them to "fix" bad guidance will be undone on the next Boost update. If the skill produces wrong component usage, upgrade Glider/Boost and re-run the installer instead.

Asset resolution. Presets referencing files under public/storage require php artisan storage:link, and paths in config are not passed through asset() automatically — decide whether presets store relative paths or URLs and be consistent. Vite-hashed assets belong in src attributes passed from the template, not baked into config.

Extension points, in order of preference:

1. Config presets — the supported customization surface; use it for anything visual.
2. Publish and override views (--tag= per the README) — for markup changes the preset system cannot express. Note this in your upgrade checklist; overridden views win over vendor updates.
3. Wrapper components — for app-specific behavior. Preferred over view overrides because it survives upgrades untouched.
4. Subclassing/replacing the component — last resort; you inherit maintenance of the whole component.

Debugging checklist for a background that will not render: confirm the view is not cached (view:clear), confirm config is not cached with stale presets (config:clear), dump the published view to inspect the resolved attributes, verify the file exists on disk, then check that the parent element has an explicit height — a background layer with cover inside a zero-height wrapper renders as nothing.