Skip to content

Render Hooks

Inject custom HTML, Livewire components, or Blade views into specific positions across the admin panel without modifying Shopper's core views.

Render hooks give you named injection points inside Shopper's admin views. Instead of overriding templates, you register a callback on a hook name and Shopper renders your content in the right place at the right time.

This is the recommended way to add content to an admin page: a banner in the sidebar of the order page, a widget above the product list, or a tracking script in the page head.

Registering a Hook

Your application registers hooks on the admin panel through the Shopper facade, in the boot() method of a service provider:

app/Providers/AppServiceProvider.php
use Shopper\Facades\Shopper;
use Shopper\View\OrderRenderHook;

public function boot(): void
{
    Shopper::renderHook(
        OrderRenderHook::DETAIL_SIDEBAR_AFTER,
        fn (): string => '<p class="text-sh-fg-muted text-sm">Ships from the Lyon warehouse.</p>',
    );
}

The text shows at the end of the sidebar of the order page, below the billing address:

Customer sidebar of an order with the line Ships from the Lyon warehouse below the billing address

The callback receives no arguments. Shopper casts what it returns to a string and outputs it as HTML without compiling it with Blade, so return plain HTML, a view, or a Livewire component rendered with Blade::render(). The HTML is not escaped: pass any value that comes from a record or a request through e(), or render it in a view with {{ }}.

An add-on registers its hooks with $panel->renderHook() in the register() method of its add-on class, as described in Render Hooks of the add-on guide.

Returning a Blade View

A view is rendered when Shopper casts it to a string, so the callback can return it as is:

app/Providers/AppServiceProvider.php
use Illuminate\Contracts\View\View;
use Shopper\Facades\Shopper;
use Shopper\View\ProductRenderHook;

Shopper::renderHook(
    ProductRenderHook::EDIT_CONTENT_AFTER,
    fn (): View => view('shopper.products.seo-checklist'),
);

Returning a Livewire Component

Because Shopper does not compile the output with Blade, a <livewire:...> tag returned as a string is printed as is. Render the tag with Blade::render():

app/Providers/AppServiceProvider.php
use Illuminate\Support\Facades\Blade;
use Shopper\Facades\Shopper;
use Shopper\View\CustomerRenderHook;

Shopper::renderHook(
    CustomerRenderHook::SHOW_SIDEBAR_AFTER,
    fn (): string => Blade::render('<livewire:customer-loyalty-points />'),
);

The callback cannot pass the customer to the component. The example below shows how a component reads the record of the page from the route.

Registering Multiple Hooks

renderHook() returns the panel, so you can chain several calls:

app/Providers/AppServiceProvider.php
use Shopper\Facades\Shopper;
use Shopper\View\LayoutRenderHook;

Shopper::renderHook(
    LayoutRenderHook::HEAD_END,
    fn (): string => '<script src="https://cdn.example.com/analytics.js" defer></script>',
)->renderHook(
    LayoutRenderHook::BODY_START,
    fn (): string => view('analytics.noscript-tag')->render(),
);

Multiple callbacks registered on the same hook are rendered in the order they were registered, concatenated together.

Disabling a Hook

Hooks registered by an add-on follow the add-on's enabled state: a disabled add-on registers none. For the hooks of your application, register them under a condition:

app/Providers/AppServiceProvider.php
use Shopper\Facades\Shopper;
use Shopper\View\OrderRenderHook;

if (config('features.custom_order_widget')) {
    Shopper::renderHook(
        OrderRenderHook::DETAIL_MAIN_AFTER,
        fn (): string => view('orders.external-status')->render(),
    );
}

Available Hooks

Each hook is a constant of a class in the Shopper\View namespace. The tables give the hook name behind each constant and the place where it renders.

The callbacks of a hook run each time the view that holds it renders. Hooks inside a Livewire page, such as the dashboard or the order page, run again when the page re-renders after an action, so keep their queries short.

Layout Hooks

LayoutRenderHook covers the global admin layout present on every page.

ConstantHook NamePosition
HEAD_STARTshopper::head.startIn <head>, after the meta tags and fonts, before the Filament styles and the Shopper theme
HEAD_ENDshopper::head.endIn <head>, after the Shopper theme, scripts and extra stylesheets
BODY_STARTshopper::body.startRight after <body>
BODY_ENDshopper::body.endRight before </body>, after the slide-over panels and the scripts
BEFORE_HEADERshopper::header.beforeAbove the top bar
AFTER_HEADERshopper::header.afterBelow the top bar
HEADER_STARTshopper::header.startIn the top bar, before the notifications, the site link and the account menu
HEADER_ENDshopper::header.endIn the top bar, after HEADER_START and before the notifications
SIDEBAR_STARTshopper::sidebar.startAt the top of the sidebar navigation
SIDEBAR_ENDshopper::sidebar.endAt the bottom of the sidebar navigation
CONTENT_STARTshopper::content.startAbove the content of the page
CONTENT_ENDshopper::content.endBelow the content of the page
CONTENT_ASIDEshopper::content.asideNext to the content of the page, for a side panel
DASHBOARD_STARTshopper::dashboard.startTop of the dashboard page
DASHBOARD_ENDshopper::dashboard.endBottom of the dashboard page
ACCOUNT_STARTshopper::account.startTop of the account page
ACCOUNT_ENDshopper::account.endBottom of the account page

The HEAD and BODY hooks also render on the sign-in pages. Check shopper()->auth()->check() in the callback before rendering content meant for signed-in users. The settings index page has no hooks: SETTINGS_INDEX_START and SETTINGS_INDEX_END do not exist in 3.x.

Product Hooks

ProductRenderHook targets the product list, product edit and variant pages.

ConstantHook NamePosition
INDEX_TABLE_BEFOREshopper::products.index.table.beforeAbove the products table
INDEX_TABLE_AFTERshopper::products.index.table.afterBelow the products table
EDIT_HEADER_AFTERshopper::product.edit.header.afterBelow the product page header
EDIT_TABS_BEFOREshopper::product.edit.tabs.beforeAbove the section menu of the product page
EDIT_TABS_ENDshopper::product.edit.tabs.endIn the section menu, after its last group
EDIT_CONTENT_BEFOREshopper::product.edit.content.beforeAbove the content of the active section
EDIT_CONTENT_AFTERshopper::product.edit.content.afterBelow the content of the active section
VARIANT_HEADER_AFTERshopper::product.variant.header.afterBelow the variant page header
VARIANT_MAIN_AFTERshopper::product.variant.main.afterAt the bottom of the main column of the variant page
VARIANT_SIDEBAR_AFTERshopper::product.variant.sidebar.afterAt the bottom of the sidebar of the variant page

To add a section with its own page to the product menu, register a product section instead of a link in EDIT_TABS_END.

Order Hooks

OrderRenderHook targets the order list, order detail, shipments, and abandoned carts pages.

ConstantHook NamePosition
INDEX_TABLE_BEFOREshopper::orders.index.table.beforeAbove the orders table
INDEX_TABLE_AFTERshopper::orders.index.table.afterBelow the orders table
DETAIL_HEADER_AFTERshopper::order.detail.header.afterBelow the order detail page header
DETAIL_CONTENT_BEFOREshopper::order.detail.content.beforeAt the top of the order content, above both columns
DETAIL_MAIN_BEFOREshopper::order.detail.main.beforeAbove the two columns, after DETAIL_CONTENT_BEFORE
DETAIL_MAIN_AFTERshopper::order.detail.main.afterAt the bottom of the main column, below the order summary
DETAIL_SIDEBAR_BEFOREshopper::order.detail.sidebar.beforeAt the top of the sidebar, above the customer card
DETAIL_SIDEBAR_AFTERshopper::order.detail.sidebar.afterAt the bottom of the sidebar, below the customer card
DETAIL_CONTENT_AFTERshopper::order.detail.content.afterAt the bottom of the order content, below both columns
SHIPMENTS_TABLE_BEFOREshopper::shipments.index.table.beforeAbove the shipments table
SHIPMENTS_TABLE_AFTERshopper::shipments.index.table.afterBelow the shipments table
ABANDONED_CARTS_TABLE_BEFOREshopper::abandoned-carts.table.beforeAbove the abandoned carts table
ABANDONED_CARTS_TABLE_AFTERshopper::abandoned-carts.table.afterBelow the abandoned carts table

Customer Hooks

CustomerRenderHook targets the customer list, customer creation and customer detail pages.

ConstantHook NamePosition
INDEX_TABLE_BEFOREshopper::customers.index.table.beforeAbove the customers table
INDEX_TABLE_AFTERshopper::customers.index.table.afterBelow the customers table
CREATE_FORM_BEFOREshopper::customer.create.form.beforeBefore the new customer form
CREATE_FORM_AFTERshopper::customer.create.form.afterAfter the new customer form
SHOW_HEADER_AFTERshopper::customer.show.header.afterBelow the customer detail header
SHOW_TABS_BEFOREshopper::customer.show.tabs.beforeAbove the customer detail tabs
SHOW_TABS_ENDshopper::customer.show.tabs.endIn the tab bar, after the last tab
SHOW_CONTENT_BEFOREshopper::customer.show.content.beforeAbove the content of the active tab
SHOW_CONTENT_AFTERshopper::customer.show.content.afterBelow the content of the active tab
SHOW_SIDEBAR_BEFOREshopper::customer.show.sidebar.beforeAt the top of the sidebar of the customer page
SHOW_SIDEBAR_AFTERshopper::customer.show.sidebar.afterAt the bottom of the sidebar of the customer page

Collection Hooks

CollectionRenderHook targets the collection list and collection edit pages.

ConstantHook NamePosition
INDEX_TABLE_BEFOREshopper::collections.index.table.beforeAbove the collections table
INDEX_TABLE_AFTERshopper::collections.index.table.afterBelow the collections table
EDIT_FORM_BEFOREshopper::collection.edit.form.beforeBefore the collection edit form
EDIT_FORM_AFTERshopper::collection.edit.form.afterAfter the collection edit form

Catalog Hooks

CatalogRenderHook covers the catalog support pages: categories, brands, tags, attributes, and reviews.

ConstantHook NamePosition
CATEGORIES_TABLE_BEFOREshopper::categories.index.table.beforeAbove the categories table
CATEGORIES_TABLE_AFTERshopper::categories.index.table.afterBelow the categories table
BRANDS_TABLE_BEFOREshopper::brands.index.table.beforeAbove the brands table
BRANDS_TABLE_AFTERshopper::brands.index.table.afterBelow the brands table
TAGS_TABLE_BEFOREshopper::tags.index.table.beforeAbove the tags table
TAGS_TABLE_AFTERshopper::tags.index.table.afterBelow the tags table
ATTRIBUTES_TABLE_BEFOREshopper::attributes.index.table.beforeAbove the attributes table
ATTRIBUTES_TABLE_AFTERshopper::attributes.index.table.afterBelow the attributes table
REVIEWS_TABLE_BEFOREshopper::reviews.index.table.beforeAbove the reviews table
REVIEWS_TABLE_AFTERshopper::reviews.index.table.afterBelow the reviews table

Sales Hooks

SalesRenderHook covers the discounts and suppliers pages.

ConstantHook NamePosition
DISCOUNTS_TABLE_BEFOREshopper::discounts.index.table.beforeAbove the discounts table
DISCOUNTS_TABLE_AFTERshopper::discounts.index.table.afterBelow the discounts table
DISCOUNT_CREATE_FORM_BEFOREshopper::discounts.create.form.beforeBefore the form of the slide-over that creates a discount
DISCOUNT_CREATE_FORM_AFTERshopper::discounts.create.form.afterAfter the form of the slide-over that creates a discount
DISCOUNT_EDIT_FORM_BEFOREshopper::discounts.edit.form.beforeBefore the discount edit form
DISCOUNT_EDIT_FORM_AFTERshopper::discounts.edit.form.afterAfter the discount edit form
SUPPLIERS_TABLE_BEFOREshopper::suppliers.index.table.beforeAbove the suppliers table
SUPPLIERS_TABLE_AFTERshopper::suppliers.index.table.afterBelow the suppliers table

Example: Injecting an External Status Badge on Order Detail

A real-world scenario: your store syncs orders to a fulfillment service (ShipStation, ShipBob, etc.) and you want to display the external status directly on the order detail page, without modifying any Shopper files.

The hook callback receives no arguments, so it cannot pass the order to your component. Instead, the hook renders a Livewire component that reads the order from the current route in its mount() method. The order detail route is {order}/detail, and the order detail page resolves {order} to the Order model. Livewire keeps the component's state on later requests, so mount() only runs on the page load.

Create the Livewire component:

app/Livewire/ExternalOrderStatus.php
namespace App\Livewire;

use App\Services\ExternalFulfillmentService;
use Illuminate\Contracts\View\View;
use Livewire\Attributes\Locked;
use Livewire\Component;

class ExternalOrderStatus extends Component
{
    #[Locked]
    public int $orderId;

    public function mount(): void
    {
        $this->orderId = request()->route('order')->id;
    }

    public function render(): View
    {
        $status = ExternalFulfillmentService::getStatus($this->orderId);

        return view('livewire.external-order-status', ['status' => $status]);
    }
}

Register the hook in your service provider:

app/Providers/AppServiceProvider.php
use Illuminate\Support\Facades\Blade;
use Shopper\Facades\Shopper;
use Shopper\View\OrderRenderHook;

public function boot(): void
{
    Shopper::renderHook(
        OrderRenderHook::DETAIL_SIDEBAR_AFTER,
        fn (): string => Blade::render('<livewire:external-order-status />'),
    );
}

Using Hook Constants vs. Raw Strings

Always use the class constants instead of raw hook name strings. They are checked by static analysis, will trigger IDE autocompletion, and won't silently break if a hook name changes in a future release. Both calls below register on the same hook:

app/Providers/AppServiceProvider.php
use Shopper\Facades\Shopper;
use Shopper\View\ProductRenderHook;

Shopper::renderHook(ProductRenderHook::EDIT_CONTENT_AFTER, fn (): string => '<p>Reviewed by the catalog team</p>');

Shopper::renderHook('shopper::product.edit.content.after', fn (): string => '<p>Reviewed by the catalog team</p>');

Last updated on

Edit on GitHub