Chat on WhatsApp
Toggle Nav
My Cart
Magento glossary

What is a Magento UI Component ?

A Magento UI Component is a declarative frontend element built from XML config + JSON layout + KnockoutJS templates + JS modules + PHP data providers. It powers every admin grid and form in Magento 2.4.x and the default Luma storefront checkout. Hyvä Themes drops UI Components on the storefront in favour of Alpine.js + Magewire, but keeps them in admin.

Need a custom UI Component? How it works

Written by Kishan Savaliya — Adobe Certified Magento & Hyvä developer, 8 years on platform

How it works

Five layers that make a UI Component render

UI Components are intentionally layered — XML config separates from data, data separates from rendering. Verbose but powerful. Here is each layer in order.

  1. 01

    XML declares the component tree

    Every UI Component starts with a layout XML reference like <uiComponent name="foo_listing"/>. That name is a pointer to a dedicated UI component XML file under view/adminhtml/ui_component/foo_listing.xml (or view/frontend/ui_component/ for Luma storefront uses). Magento parses the file at request time, resolves the component tree, and hands the result to the rendering layer. Without this XML entry-point there is no UI Component — it is the contract Magento looks for.

  2. 02

    The UI component XML defines children, data source, providers

    Inside the UI component XML you declare child components (columns, fields, filters, buttons, modals), a dataSource block pointing at the PHP data provider, and config blocks for paging, sorting, and column rendering. The XML can nest 5 – 10 levels deep on real admin grids — every column, every filter, every action button is a child component. Magento merges the XML files across modules at compile time so third-party extensions can inject columns into existing grids.

  3. 03

    PHP data provider implements DataProviderInterface

    The dataSource in the XML points to a PHP class that implements Magento\Ui\DataProvider\DataProviderInterface. It returns the rows for a grid, the field values for a form, the meta-config (column labels, field types, validation rules). The provider is where you wire collection filters, joins, custom column data — basically anything that needs PHP logic to feed the component. Customer grid, product grid, sales order grid all have their own data providers.

  4. 04

    Knockout templates render the markup; JS modules wire bindings

    The actual HTML for each component lives in a KnockoutJS template (.html file) under view/base/web/templates/ or per-component. Knockout’s data-bind attributes wire DOM nodes to observable JavaScript view models. Each component also has a JS module (RequireJS) that defines the view model — what data it observes, how it reacts to events, what it does on click. This is the most verbose layer and the hardest to debug.

  5. 05

    Page boots via x-magento-init, Knockout binds to DOM

    When the page renders, Magento emits a <script type="text/x-magento-init"> JSON blob with the component config. The Magento bootstrap JS reads it, instantiates the JS modules via RequireJS, and Knockout walks the DOM applying bindings. Once boot completes, the page is interactive — filters update the grid via AJAX, forms validate on blur, modals open without page reload. The bootstrap step is exactly where Hyvä cuts the cord on the storefront, replacing the whole chain with Alpine.

When to use

Four scenarios where UI Components are the right answer

UI Components are not universally needed — but for these four cases they are either mandatory or the obvious pragmatic choice.

  • Building a custom admin grid or listing

    For any new admin grid — list of imports, log of webhook calls, queue of pending approvals — the UI Component pattern is mandatory. There is no second blessed way to build an admin grid in Magento 2.4.x: you write the listing XML, the data provider, optional action columns, and you get sorting, filtering, paging, bookmarks, mass actions, and inline-edit for free. Trying to bypass with a custom PHP-rendered table costs more time and ships fewer features.

  • Building a custom admin form

    Admin forms — edit pages for any custom entity (vendor, location, custom block, custom rule) — follow the same UI Component pattern. The form XML defines fieldsets, fields, validation, dependent visibility (show field B only if field A = X). You get JS validation, AJAX save, the standard admin styling, and the back/save/save-and-continue button row for free. Hand-rolling a form in PHTML means re-implementing all of that and losing admin theme consistency.

  • Extending an existing admin grid

    Adding a column, filter, mass-action, or bookmark view to an existing admin grid (customer grid, product grid, order grid) means dropping a UI component XML file into your module that gets merged with the core one at compile time. Five lines of XML can add a sortable, filterable column to the sales order grid. This is one of the cleanest extension points in Magento 2 — third-party extensions use it constantly.

  • Legacy Luma storefront widgets (checkout, account)

    On a Luma storefront UI Components also drive the entire default checkout (steps, shipping methods, payment methods, summary), the mini-cart, the customer account dashboard, and the wishlist. If you are maintaining or extending a Luma store in 2026, you still touch UI Components on the storefront side. New stores on Hyvä bypass all of this — Alpine + Magewire replace the storefront UI Component layer entirely.

Common mistakes

Three traps that turn a UI Component build into a long debug session

Every "why isn't my UI Component working" ticket I get on Upwork hits one of these three. Avoid them and the build runs smooth.

  • Trying to use UI Components on a Hyvä storefront

    Hyvä strips KnockoutJS, RequireJS, and the Magento UI bootstrap from the storefront entirely. Dropping a UI Component PHTML or XML expecting it to render on a Hyvä page silently does nothing — there is no Knockout binding pass to wire it up. The Hyvä equivalents are Alpine.js for client-side reactivity and Magewire for server-driven state. Always check whether the page you are touching is Hyvä storefront, Luma storefront, or admin before picking the pattern.

  • Forgetting to clear var/view_preprocessed/ after XML changes

    Magento caches the merged UI component XML aggressively. After editing your component XML, the old merged version sticks until you wipe var/view_preprocessed/ and var/cache/ (or run cache:flush plus a static-content redeploy). Hours of "why isn’t my new column showing up" debugging come down to this one cache. Build the cache-wipe step into your dev workflow.

  • Nesting 5 – 10 levels deep without flattening

    Real-world admin grid XML routinely nests <listing> > <dataSource> > <listingToolbar> > <filters> > <filterSelect> > <settings> > <options> > <option>. Eight levels of XML, each with its own attributes, no IDE auto-complete on the merged result. Debugging means reading the compiled XML in generated/code/. Flatten where the pattern allows, copy from core examples, and lean on tools like n98-magerun2 to dump the merged config.

Related concepts

Five neighbour concepts most readers want to look at next. Click through for the full deep-dive.

FAQ

Magento UI Components — frequently asked questions

  • UI Component vs Layout XML — what is the difference?
    Layout XML places blocks and containers on a page — it answers "what goes where" at the page-skeleton level. UI Component XML defines a self-contained interactive widget (grid, form, modal) — it answers "how does this one widget behave and what data does it show". You always need Layout XML to get the page rendered; you add a UI Component XML when one of the placed blocks happens to be a grid or form that wants the UI Component pattern. Layout XML reaches into UI Component XML via <code><uiComponent name="foo_listing"/></code>, but the two systems are otherwise distinct files, distinct namespaces, distinct caching layers.
  • Do I still need UI Components if I am on Hyvä?
    Yes — for admin. No — for storefront. Hyvä replaces the storefront frontend (PLP, PDP, cart, checkout, mini-cart, customer account) with a Tailwind + Alpine + Magewire stack that has no Knockout or UI Component bootstrap. The Magento admin panel is untouched by Hyvä — every admin grid, form, and listing still uses the UI Component pattern exactly as Adobe ships it. If you are building a custom admin module on a Hyvä store, you still write UI Component XML for any grid or form in it.
  • Why is KnockoutJS still in Magento 2.4.x?
    Knockout was the leading reactive JS library when Magento 2 was designed in 2013 – 2015. Replacing it now means rewriting every admin grid, form, checkout step, and Luma storefront widget — thousands of files across Magento core, official extensions, and the marketplace. Adobe has chosen stability over modernisation on this front: Knockout keeps working, breaks nothing, and the storefront migration path (Hyvä) addresses the visible performance pain without touching the admin. Expect Knockout to remain in the codebase indefinitely for admin, even as the storefront moves on.
  • How do I add a column to an existing admin grid?
    Create a <code>view/adminhtml/ui_component/<grid_name>.xml</code> file in your module with the same root <code>name</code> as the core grid (e.g. <code>customer_listing</code>, <code>sales_order_grid</code>). Inside it, add a <code><columns name="..."></code> block with a single <code><column name="my_new_col"></code> child declaring the column’s label, sort, filter, and data type. Magento merges your file with the core one at compile time. If the column data needs to come from a custom field you populate at save time, add a join in a data provider plugin too. Five to fifteen lines of XML covers most cases.
  • Can I write a UI Component in Vue or React?
    No — not in the Magento UI Component sense. The pattern is locked to KnockoutJS templates + RequireJS modules + the Magento UI bootstrap. You can place a Vue or React app inside an admin page (drop a div, mount a frontend bundle, communicate via Magento REST/GraphQL), but it will not participate in the UI Component lifecycle — no grid bookmarks, no mass-action toolbar, no admin form save row. For pure custom dashboards in the admin, sometimes a small React app is the pragmatic choice. For anything that needs to integrate with the admin’s grid/form conventions, stick with UI Components.
  • Are UI Components going to be replaced?
    Adobe has not announced a replacement for UI Components in the admin. The Hyvä community has effectively replaced them for storefront use (Alpine + Magewire is the consensus), and there are early experiments inside Adobe around React-based admin components, but nothing officially shipped or roadmapped as of 2026. For new builds in 2026 the safe assumption is: UI Components stay for admin, are gone on Hyvä storefronts, are still in use on Luma storefronts. Plan migrations accordingly.
UI Component build

Need a custom admin grid, form, or UI Component built?

Send your requirement — I will reply with a fixed-price quote, sample XML, and earliest start date. Admin grids, forms, modals, mass actions, and bookmark views all covered. 24-business-hour turnaround.

Get a UI Component quote Hire me directly