Components

Creating components

Creating a basic Magewire component takes just a few minutes and requires only two or three files, depending on whether you already have a layout handle. At its core, a Magewire component consists of two main files: a PHP class that handles the logic and a template responsible for rendering the HTML on the frontend.

In the following example, we assume you are using layout XML to inject a Magewire component onto a page. For more advanced use cases, we recommend exploring the in-depth documentation, where concepts like the resolver mechanism will most likely play a role.

1. Create the component class

Create the component below inside your Magento module:

<?php

declare(strict_types=1);

namespace Vendor\Module\Magewire;

use Magewirephp\Magewire\Component;

class Counter extends Component
{
    public int $count = 0;

    public function increment(): void
    {
        $this->count++;
    }
}

Public properties hold the component state. Public methods can be called from the template, so treat their arguments as untrusted input and perform the same validation and authorization you would use in a controller.

2. Create the template

The corresponding template reads state through the injected $magewire variable:

<div>
    <span>
        <?= $escaper->escapeHtml(__('Counter: %1', $magewire->count)) ?>
    </span>

    <button type="button" wire:click="increment">
        <?= $escaper->escapeHtml(__('Increase')) ?>
    </button>
</div>

Every component template must have one root HTML element. Magewire attaches the component snapshot to that element and morphs its contents after an update.

3. Bind it in layout XML

Add a block to the layout handle where the component should appear:

<referenceContainer name="content">
    <block name="vendor.module.counter"
           template="Vendor_Module::magewire/counter.phtml">
        <arguments>
            <argument name="magewire" xsi:type="object">
                Vendor\Module\Magewire\Counter
            </argument>
        </arguments>
    </block>
</referenceContainer>

The built-in layout resolver turns the block's magewire argument into the component instance. Custom resolvers are available for integrations that cannot use this standard block-and-argument shape.

4. Clear layout caches and try it

bin/magento cache:clean layout full_page

Open the page represented by the layout handle. Clicking Increase sends a Magewire update request, calls increment(), renders the template again, and morphs the changed counter into the existing DOM.

Block arguments

Magewire components are bound to Magento blocks through layout XML <argument> entries. Beyond the magewire argument that declares the component itself, a structured argument system lets you pass data straight into a component from layout XML without custom ViewModel or constructor wiring.

Arguments are extracted from the block during the assembly phase, after the component has been resolved and mounted.

Binding a component

The magewire argument tells the resolver which component to bind to the block. The built-in LayoutResolver accepts three formats:

<!-- 1. Direct object binding (most common) -->
<argument name="magewire" xsi:type="object">Vendor\Module\Magewire\MyComponent</argument>

<!-- 2. Array with an object type, allowing extra config alongside the component -->
<argument name="magewire" xsi:type="array">
    <item name="type" xsi:type="object">Vendor\Module\Magewire\MyComponent</item>
</argument>

<!-- 3. Array with a boolean type for a dynamic component with no physical class -->
<argument name="magewire" xsi:type="array">
    <item name="type" xsi:type="boolean">true</item>
</argument>

Public arguments

Arguments prefixed with magewire. become component properties. The prefix is stripped and the kebab-case key is converted to camelCase before it is matched against a public property on the component.

<block name="my.component" template="Vendor_Module::my-component.phtml">
    <arguments>
        <argument name="magewire" xsi:type="object">Vendor\Module\Magewire\MyComponent</argument>
        <argument name="magewire.product-id" xsi:type="number">42</argument>
        <argument name="magewire.sort-order" xsi:type="string">price</argument>
    </arguments>
</block>

The keys above map as follows:

Group arguments

Arguments prefixed with magewire:{group}:{key} are collected into named groups rather than being assigned directly to properties. This keeps related values together and lets a component (or resolver) request a whole group at once.

<block name="my.component" template="Vendor_Module::my-component.phtml">
    <arguments>
        <argument name="magewire" xsi:type="object">Vendor\Module\Magewire\MyComponent</argument>
        <argument name="magewire:mount:category-id" xsi:type="number">10</argument>
        <argument name="magewire:mount:page-size" xsi:type="number">20</argument>
        <argument name="magewire:config:cache-ttl" xsi:type="number">3600</argument>
    </arguments>
</block>

The mount group is passed to your component's mount() method as named parameters on the initial render:

public function mount(int $categoryId = 0, int $pageSize = 10): void
{
    // $categoryId = 10, $pageSize = 20 (from magewire:mount:*)
}

Any group can also be read directly from the argument API inside a resolver or feature:

$arguments->forMount();          // ['categoryId' => 10, 'pageSize' => 20]
$arguments->forGroup('config');  // ['cacheTtl' => 3600]
$arguments->toParams();          // All public arguments as an array

Reserved keys

A few magewire: keys are reserved by the framework and are not treated as group arguments:

<argument name="magewire:resolver" xsi:type="string">widget</argument>
<argument name="magewire:alias" xsi:type="string">shipping-form</argument>

For more on how a block becomes a component and how resolvers consume these arguments, see the Resolvers documentation.