README

A lightweight Laravel package that shows a page preloader until the document is ready.

Features

Blade directives for CSS and JS includes.
Blade component for preloader markup.
Publishable assets (CSS, JS, SVG image).
Works with Laravel package auto-discovery.

Requirements

PHP 8.1 or higher.
Laravel application (auto-discovery is used).
jQuery available in your layout (the package JavaScript depends on it).

Installation

Install the package:

composer require mosamy/preloader

Publish assets to your app public directory:

php artisan vendor:publish --provider="Mosamy\Preloader\PreloaderServiceProvider" --tag="assets"

Published files:

public/css/preloader.css
public/js/preloader.js
public/images/preloader.svg

Basic Usage

Add the style directive in your layout head:

@PreloaderStyle

Add the component at the beginning of body content:

<x-preloader::init />

Add the script directive before the closing body tag:

@PreloaderJs

Full example:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    @PreloaderStyle
</head>
<body>
    <x-preloader::init />

    {{-- Your page content --}}

    @PreloaderJs
</body>
</html>

How It Works

The component renders a fullscreen overlay with an image.
CSS temporarily sets body overflow to hidden while loading.
On document ready, JavaScript removes the overlay and restores body overflow.

Important Notes

jQuery must be loaded before @PreloaderJs.
If assets are not published, the preloader files will return 404.
Asset paths are currently fixed to:
- /css/preloader.css
- /js/preloader.js
- /images/preloader.svg

Customization

After publishing assets, you can edit these files in your app:

public/css/preloader.css for colors, sizing, and overlay look.
public/images/preloader.svg for custom loader graphics.
public/js/preloader.js for custom hide timing/logic.

Troubleshooting

If the preloader stays visible:

Confirm jQuery is loaded on the page.
Check browser console for JavaScript errors.
Verify published files exist under public/css, public/js, and public/images.
Clear Laravel caches:

php artisan optimize:clear

License

MIT

mosamy / preloader

Maintainers

Package info

Statistics

Security