abr4xas / clarity-laravel
Easy integration of Microsoft Clarity into your Laravel application.
Fund package maintenance!
angelcruz.dev/donate
Installs: 37 209
Dependents: 0
Suggesters: 0
Security: 0
Stars: 56
Watchers: 1
Forks: 2
pkg:composer/abr4xas/clarity-laravel
Requires
- php: ^8.3
- spatie/laravel-package-tools: ^1.92.7
Requires (Dev)
- laravel/pint: ^1.25.1
- orchestra/testbench: ^10.6.0
- pestphp/pest: ^4.1.1
- pestphp/pest-plugin-laravel: ^4.0
- rector/rector: ^2.2
This package is auto-updated.
Last update: 2025-10-09 00:34:39 UTC
README
Easy integration of Microsoft Clarity into your Laravel application.
Installation
You can install the package via composer:
composer require abr4xas/clarity-laravel
You can publish the config file with:
php artisan vendor:publish --tag="clarity-config"
This is the contents of the published config file:
<?php return [ 'id' => env('CLARITY_ID', 'XXXXXX'), 'enabled' => env('CLARITY_ENABLED', true), ];
Optionally, you can publish the views using
php artisan vendor:publish --tag="clarity-views"
Usage
General Tracking
- Create an account: The first thing you need to do is create an account on Microsoft Clarity. You can sign up on their website and follow the steps to create your account. Then, get your tracking code and that's it.
- Simply add the blade components to your base layout files.
The enabled
attribute is optional, but can be used to control the tags integration from blade files that extend the base layout. It accepts true/false
.
This can still be controlled globally via the .env
file should you need to disable the integration global on different environments as well.
<!-- Should be placed in the head --> <x-clarity::script :enabled="$enabled" />
Custom Tags API
Microsoft Clarity's Custom Tags API allows you to segment and filter sessions on the Clarity dashboard using custom metadata. This is useful for tracking user roles, subscription plans, feature flags, A/B test variants, and more.
Using the Blade Component
<!-- Set a single value --> <x-clarity::tag key="plan" :values="['premium']" /> <!-- Set multiple values --> <x-clarity::tag key="features" :values="['chat', 'video', 'notifications']" /> <!-- Dynamic values --> <x-clarity::tag key="user_role" :values="[auth()->user()->role]" />
Using the Helper Function
For more programmatic use cases, you can use the clarity_tag()
helper function anywhere in your application:
// In a controller clarity_tag('subscription', 'pro'); // Multiple values clarity_tag('permissions', 'read', 'write', 'admin'); // Array of values clarity_tag('features', ['feature_a', 'feature_b']); // In middleware class TrackUserSegment { public function handle($request, Closure $next) { if (auth()->check()) { clarity_tag('user_segment', auth()->user()->segment); } return $next($request); } }
The helper will return the rendered script tag which you can echo in your views, or it will return null
if Clarity is disabled.
Identify API
To implement the Identify API, use identify
component.
Set CLARITY_IDENTIFICATION_ENABLED
value to true
on the env file.
Attributes:
user
attribute is required accepts the User Model instance or any object. Theemail
andname
attributes are used.enabled
attribute is optional.custom_session_id
attribute is optional.custom_page_id
attribute is optional.
@auth <x-clarity::identify :user="request()->user()"/> @endauth
This will compile as:
window.clarity("identify", "user@example.com", null, null, "Username")
Using the Helper Function
You can also use the clarity_identify()
helper for programmatic identification:
// Basic usage clarity_identify(auth()->user()); // With custom session and page IDs clarity_identify( user: auth()->user(), customSessionId: 'custom-session-123', customPageId: 'checkout-page' );
Available Helper Functions
This package provides convenient helper functions for use anywhere in your Laravel application:
clarity_tag(string $key, mixed ...$values): ?string
- Set custom tags for session filteringclarity_identify(object $user, ?string $customSessionId = null, ?string $customPageId = null): ?string
- Identify a user in the current session
These helpers respect your configuration settings and will return null
when Clarity is disabled.
Testing
composer test
Changelog
Please see CHANGELOG for more information on what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Security Vulnerabilities
Please review our security policy on how to report security vulnerabilities.
Credits
License
The MIT License (MIT). Please see License File for more information.
This package is strongly inspired by Google Tag Manager for Laravel created by @awcodes.