The Beginners Guide to Magento Blocks and Widgets

Blocks and Widgets are the key layout features in Magento. These two features are very closely linked, and are often used together.

One way to think about Blocks is that they are mini-Pages. A Block can also contain text, images, video and more. But because Blocks are smaller, you will see them around the edges of your site. Blocks are often inserted into headers, sidebars and footers.

However, Blocks are placed using Widgets. First you create a Block, and then you use a Widget to decide where that Block will be displayed.

Let’s walk you through some examples and show you how Blocks and Widgets work in Magento.

This guide is taken from Magento 2 Explained, the best-selling book for Magento 2. We use the example of a store called “Orangeville” in that book, so you’ll see it referred to here.

Creating Magento Blocks Explained

Let’s go through the process of creating our first Block. This will contain an HTML link.

  • Go to “Content”, and then “Blocks”.
  • Click “Add New Block” in the top-right corner.

add new magento block

  • Enter “Key Links” as the “Block Title”. This is what visitors will see on the screen.
  • Enter “key_links” as the Identifier. This string is what Magento uses to identify the block, but visitors will never see it.

key links magento block

  • Click the bullet icon in the editor toolbar:

editing magento block

  • Type “About Orangeville” as a bullet point:
  • Select the “About Orangeville” text and click the link icon.

link inside magento block

  • You will now see a pop-up window. Enter the URL of your “About Orangeville” page. If you’re not sure what this is, you can open your Magento site in a new browser tab and find the URL, which is likely to be
  • Click “Insert”.
  • You now have an “About Orangeville” link inside your Block:

about orangeville

  • Click “Save Block”.

Creating Magento Widgets Explained

We now have the challenge of placing your block into your site design. This is where Magento’s Widgets come in useful. In Magento, a Block is just a piece of content. It’s the Widget that controls the placement of the Block.

However, that’s not all a Widget can do. A Widget can place our simple, new Blocks, but it can also place many other features.

  • Go to “Content”, and then “Widgets”.
  • Click “Add Widget”.
  • For “Type”, choose “CMS Static Block”.
  • For “Design Theme”, choose “Magento Luma”.
  • Click “Continue”.

create magent block

  • Enter “Key Orangeville Links” for the “Widget Title”.
  • Under “Assign to Store Views”, select “All Store Views”.

key links magento block

Next, we’re going to control which URLs this Block appears on.

  • Click “Add Layout Update”.

magento layout updates

  • Choose “All Pages”.

magento all pages layout

  • Choose “CMS Footer Links” for the “Container” option.

magento cms footer

Both of these choices, “All Pages” and “CMS Footer Links”, may not make much sense to you yet. However, we’ll finish creating the widget and later in the chapter, in the section called, “Magento Widget Placement Explained”, we’ll explain more about why we made these choices.

Under “Layout Updates”, we’re going to make a second choice for where to place our widget.

  • Choose “All Product Types”.
  • Choose “CMS Footer Links” again.
  • After adding both of these options, your screen will look like the image below.

magento block placement

At this point, you’ve created the Widget and told Magento where it should appear on your site: this Widget will appear on all our Pages and all our Products.

Now it’s time to choose the content of the Widget, which will be the Block you created earlier.

  • Click “Widget Options” in the sidebar.
  • Click “Select Block”.

select magento block

  • Now you can choose the “Key links” block you created earlier:

select magento block

  • Click “Save”.
  • Visit the front of your site, and you’ll see your link is now published in the footer. You created a Block with the content, and published it inside a Widget.

new magento block visible

Creating Blocks and Widgets Together

There are definitely some tricky steps as you create Blocks and Widgets. So let’s try this whole process together. We’ll create a second Block and place it on our site with the help of a Widget. This Block will tell people that we have a 100% satisfaction guarantee.

  • Go to “Content”, and then “Blocks”.
  • Click “Add New Block”.
  • Title: Satisfaction Guaranteed
  • Identifier: guarantee

new magento block

  • Enter text for your Block. I wrote “Here at Orangeville, your satisfaction is our top priority. If you’re not happy, we’ll refund your money.”

new image block magento

Next, we’re going to upload an image for our block. 

  • Place your cursor into the main content area, below the text that you just wrote.
  • Click the tree icon in your editor toolbar.
  • When you see the pop-up box, click the small box icon.
  • Find an image that you can upload. I’ve choosen a 100% badge.

add image magento block

  • Click “Insert File”.
  • Image Description: Satisfaction Guarantee 
  • Click “Insert”.

uploading magento image

  • You now have a Block that contains both text and your new image.
  • Click “Save Block” to finish creating this Block.

new magento block with image

Next, let’s create the Widget that will display this Block on our site.

  • Go to “Content”, and then “Widgets”.
  • Click “Add Widget”.
  • Type: CMS Static Block
  • Design Theme: Magento Luma

magento block settings

  • Widget Title: Satisfaction Guaranteed
  • Assign to Store Views: All Store Views

magento block properties

  • Layout Update: Anchor Categories
  • Container: Sidebar Main
  • Click “Widget Options” and choose the “Satisfaction Guaranteed” Block that you just created.

magento widget options choose

  • Click “Save”.
  • Visit the front of your site. Click on one of the category links in the top menu. In the image below, I clicked on “Fruit”. You will now see your guarantee Block in the left sidebar:

magento block in sidebar

Magento Widget Placement Explained

One common question I get from Magento  learners is about the placement of Widgets.

How do you know to choose “CMS Footer Links” or “Sidebar Main” for the Container? After all, there are 22 different choices, as you can see in the image below.

What’s the difference between “After Page Header” and “After Page Header Top”? What’s the difference between “Page Footer” and “Page Footer Container”? Those names are so similar that they can definitely be confusing.

magento widget containers

Unfortunately, there’s no sure way to tell in advance, although the name will give you a good idea of the placement:

  • After Page Header: This is likely to be under the main menu.
  • Main Content Bottom: This is probably low down on central part of the screen, underneath our products or Page content.
  • Page Top: This will appear high up on Pages, but not on Product screens.

It’s worth noting that these options change, even on the same site. If you are trying to place a Block and choose “All Product Types” for your Widget’s “Layout Options”, then you will get a different set of choices, shown in the image below. These options provide some placements that only make sense for your product screens. For example, you now see choices that include “Product social links container” and “Review Form Fields Before”. Those Widget placements don’t make sense anywhere except for on Product screens.

On the other hand, this list can sometimes be much shorter. In the next part of this chapter, we’ll see that some Widgets only come with three Container options.

So, there’s no guaranteed way to tell exactly where your Widget will appear if you choose a particular Container. There will be some testing and experimentation involved as you test these different options.

magento widget container product

Magento Blocks and Widgets Summary

Blocks and Widgets allow you to add new items to your site’s design. However, there are some elements on your site that can’t easily be modified or replaced from Magento’s admin interface. They look like they should be Blocks and Widgets, but Magento has not created them that way. So, I created a page with instructions for updating some of those default elements.

If you’re ready to learn more about Magento, check out Magento 2 Explained, the best-selling book for Magento 2.

We also have some more great Magento tutorials online, including:


  • Steve Burge

    Steve is the founder of OSTraining. Originally from the UK, he now lives in Sarasota in the USA. Steve's work straddles the line between teaching and web development.

0 0 votes
Article Rating
Notify of

Newest Most Voted
Inline Feedbacks
View all comments
Ruchi Marwah
Ruchi Marwah
4 years ago

Awesome method of teaching….he understands the probable questions in a learner’s mind. Thanks

Gerald Cottrell
Gerald Cottrell
3 years ago

Wow! what a post, each and every detail is so helpful. 

3 years ago

Magento is horrible. 

Would love your thoughts, please comment.x