Basics

A Magewire component combines a PHP class with a .phtml template. Magento layout XML places the component on a page; Magewire then keeps its public state and the rendered DOM synchronized across update requests.

Before continuing, install and enable Magewire as described on the documentation home page.

Build a counter

The following example creates a complete component, binds it to a Magento block, and calls a PHP action from the browser.

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.

The request cycle

The counter demonstrates Magewire's normal request cycle:

1. Magento renders the layout block and component template.
2. Magewire serializes the component's public state into a signed snapshot.
3. wire:click="increment" sends that snapshot and the requested action to the Magewire update route.
4. Magewire reconstructs the component, calls increment(), and renders the template again.
5. The browser processes the response and morphs only the changed DOM.

Component snapshots are browser-visible data. Never put secrets in public properties, and always authorize sensitive actions on the server.

Passing initial values from layout XML

Use a magewire. argument for a public property and a magewire:mount: argument for a named mount() parameter:

<argument name="magewire.label" xsi:type="string">Items</argument>
<argument name="magewire:mount:start" xsi:type="number">19</argument>

public string $label = 'Counter';

public function mount(int $start = 0): void
{
    $this->count = $start;
}

The layout resolver converts kebab-case argument names to camelCase. For example, magewire:mount:page-size is passed as $pageSize.

See Components for every supported binding shape and argument group. Continue with Properties, Actions, and the HTML directives when you are ready to add real behavior.