WooCommerce module

Products block

WooCommerce products in a grid, list, carousel or slider — latest, featured, on sale, best selling, top rated, hand-picked, related, upsells or cross-sells.

Overview

The Products block shows WooCommerce products anywhere: on the homepage, landing pages, the cart page or product templates. Pick which products (nine sources, from “Latest” to “Cross-sells of the cart”), filter by category or tag, and choose a grid, list, carousel or slider. Cards can show a second image on hover, a sale badge, category, rating, price, an add-to-cart button and the short description.

At a glance

Block name: wpbb/products
Module: WooCommerce
Find it by searching: Products
Requires: WooCommerce installed and active
Works with: WooCommerce must be installed and active. The WooCommerce module only appears when it is.
Loads JavaScript on the site: Only the shared carousel script, for the Carousel and Slider layouts

When and why to use it

Featured or on-sale products on the homepage.
Related products and upsells on product pages.
Cross-sells on the cart page.
Hand-picked collections on landing pages.

Example scenarios

Homepage: On sale, 8 products, Carousel, 4/3/2 columns.
Product template: Related products, 4 products, Grid.
Cart page: Cross-sells of the cart, 4 products.

How to add the Products block

Open the editor. In your WordPress dashboard go to Pages (or Posts) and click the page you want to edit, or click Add New. For headers, footers and templates, use Appearance → Editor (block themes).
Add a new block. Click the blue + (Block Inserter) button in the top-left corner, or the small + that appears where you want the block. You can also type / on an empty line.
Search for the block. Type Products in the search field. Brigade Blocks appear in the Brigade Blocks category and show the coral block icon.
Insert it. Click Products in the results. The block appears with a live preview of your latest products.
Configure the content. Edit the text directly on the block, then open the Settings tab (gear icon) in the right-hand sidebar for the options described below. If the sidebar is hidden, click the gear icon in the top-right corner.
Customise the design. Switch to the Styles tab (half-filled circle icon) to change colours, spacing, borders and more — see Design & styling.
Save or publish. Click Save draft to keep working later, Preview to check it, or Publish / Update to make it live.

Content settings

You set up this block in two places: on the block itself in the editor, and in the Settings tab (gear icon) of the sidebar on the right. Every option is listed below, with its default value.

On the block (in the editor canvas)

Live preview

What it does: Shows your real products in the editor.
What to enter or choose: Nothing to type — use the sidebar.
How to use it: Select the block and use the Settings tab.
When to use it: —
Example: —
Result: Updates as you change settings.

Settings panel: Products

Show

What it does: Which products are listed.
What to enter or choose: One of: Latest products, Featured products, On sale, Best selling, Top rated, Hand-picked products, Related products, Upsells of this product, Cross-sells of the cart.
Default: Latest products
How to use it: Open the dropdown and pick an option.
When to use it: Featured = products starred in WooCommerce. Related and Upsells use the product being viewed (single product template or on a product). Cross-sells use the products in the visitor’s cart — ideal on the cart page.
Example: Featured on the homepage.
Result: The preview updates.

ProductsShown when Show is Hand-picked products

What it does: The exact products to show, in the order picked.
What to enter or choose: Search and pick products.
Default: None selected
How to use it: Start typing a product name and pick it from the suggestions.
When to use it: Curated collections.
Example: Your three bestsellers.
Result: Only those products.

CategoriesShown when Show is Latest, Featured, On sale, Best selling or Top rated

What it does: Limits products to these categories.
What to enter or choose: Product categories (empty = any).
Default: None selected
How to use it: Start typing a name and pick it from the suggestions. Add several if needed; remove one with its ×.
When to use it: To show one department.
Example: “Shoes”.
Result: Only products in the chosen categories.

TagsShown when Show is Latest, Featured, On sale, Best selling or Top rated

What it does: Limits products to these tags.
What to enter or choose: Product tags (empty = any).
Default: None selected
How to use it: Start typing a name and pick it from the suggestions. Add several if needed; remove one with its ×.
When to use it: Seasonal collections.
Example: “Summer”.
Result: Only products with the chosen tags.

Number of products

What it does: How many products are shown.
What to enter or choose: A number from 1 to 24.
Default: 8
How to use it: Drag the slider, or type a number in the box next to it.
When to use it: Always.
Example: 8.
Result: More or fewer cards.

Order byShown when Show is not Best selling, Top rated or Hand-picked (those have their own order)

What it does: How products are sorted.
What to enter or choose: One of: Newest, Name, Price, Popularity (sales), Average rating, Custom order (menu order), Random.
Default: Newest
How to use it: Open the dropdown and pick an option.
When to use it: Always optional.
Example: Price.
Result: The order changes.

DirectionShown when Order by is Newest, Name, Price or Custom order

What it does: Sort direction.
What to enter or choose: One of: Descending, Ascending.
Default: Descending
How to use it: Click one of the buttons in the group.
When to use it: Always optional.
Example: Ascending price = cheapest first.
Result: The order is reversed.

Hide out-of-stock products

What it does: Leaves out products that are out of stock.
What to enter or choose: On or off.
Default: Off
How to use it: Click the switch to turn it on (blue) or off.
When to use it: Usually on for marketing sections.
Example: On for promotions.
Result: Only purchasable stock is shown.

Settings panel: Layout

Layout

What it does: How products are arranged.
What to enter or choose: One of: Grid, List, Carousel, Slider (one at a time).
Default: Grid
How to use it: Open the dropdown and pick an option.
When to use it: Grid for most pages; List for sidebars.
Example: Carousel for “You may also like”.
Result: Changing the layout applies suitable starting values for settings you have not changed.

Columns (desktop)Shown when Layout is Grid or CarouselDesktop

What it does: Items per row on large screens.
What to enter or choose: A number from 1 to 6.
Default: 4
How to use it: Drag the slider, or type a number in the box next to it.
When to use it: Always.
Example: 4.
Result: Items resize to fit.

Columns (tablet)Shown when Layout is Grid or CarouselTablet

What it does: Items per row below 1024px.
What to enter or choose: A number from 1 to 4.
Default: 3
How to use it: Drag the slider, or type a number in the box next to it.
When to use it: Always.
Example: 3.
Result: Applies up to 1023px wide.

Columns (mobile)Shown when Layout is Grid or CarouselMobile

What it does: Items per row below 600px.
What to enter or choose: A number from 1 to 2.
Default: 2
How to use it: Drag the slider, or type a number in the box next to it.
When to use it: Always.
Example: 2.
Result: Applies up to 599px wide.

Card style

What it does: Bordered cards or plain items.
What to enter or choose: One of: Card, Plain.
Default: Card
How to use it: Click one of the buttons in the group.
When to use it: Always optional.
Example: Plain on a white page.
Result: The card design changes.

Image ratio

What it does: The product image shape.
What to enter or choose: One of: 1:1, 3:4 (portrait), 4:3, Original.
Default: 1:1
How to use it: Open the dropdown and pick an option.
When to use it: Match your product photos.
Example: 3:4 for fashion.
Result: Images are fitted into that shape.

Settings panel: Card content

Image

What it does: The product image.
What to enter or choose: On or off.
Default: On
How to use it: Click the switch to turn it on (blue) or off.
When to use it: Optional.
Example: On.
Result: Image is shown or hidden on every card.

Second image on hoverShown when Image is on

What it does: Swaps to the first gallery image when the pointer is over the card.
What to enter or choose: On or off.
Default: On
How to use it: Click the switch to turn it on (blue) or off.
When to use it: Optional.
Example: On.
Result: Products with a gallery show their second image on hover.

Sale / sold-out badge

What it does: A “Sale” or “Sold out” badge on the image.
What to enter or choose: On or off.
Default: On
How to use it: Click the switch to turn it on (blue) or off.
When to use it: Optional.
Example: On.
Result: Sale / sold-out badge is shown or hidden on every card.

Rating

What it does: The star rating (products with reviews only).
What to enter or choose: On or off.
Default: On
How to use it: Click the switch to turn it on (blue) or off.
When to use it: Optional.
Example: On.
Result: Rating is shown or hidden on every card.

Price

What it does: The price, including sale prices.
What to enter or choose: On or off.
Default: On
How to use it: Click the switch to turn it on (blue) or off.
When to use it: Optional.
Example: On.
Result: Price is shown or hidden on every card.

Add to cart button

What it does: WooCommerce’s add-to-cart button (or “Select options” / “Read more” for products that need a choice).
What to enter or choose: On or off.
Default: On
How to use it: Click the switch to turn it on (blue) or off.
When to use it: Optional.
Example: On.
Result: Add to cart button is shown or hidden on every card.

Short description

What it does: The product short description.
What to enter or choose: On or off.
Default: Off
How to use it: Click the switch to turn it on (blue) or off.
When to use it: Optional.
Example: On.
Result: Short description is shown or hidden on every card.

Title tag

What it does: The heading level of product names.
What to enter or choose: One of: H2, H3, H4, H5, H6, P.
Default: H3
How to use it: Open the dropdown and pick an option.
When to use it: Match the page structure.
Example: H3.
Result: Structure only.

Message when empty (editor only)

What it does: A note shown in the editor when no products match.
What to enter or choose: Any text.
Default: Empty
How to use it: Type into the text field. Changes appear in the preview right away.
When to use it: To remind editors why the block is empty.
Example: “Add products to the Summer tag.”
Result: Visitors never see it — the block is simply hidden when empty.

Settings panel: Carousel

Only shown for the Carousel and Slider layouts. The panel starts closed.

Arrows

What it does: Shows previous/next arrow buttons.
What to enter or choose: On or off.
Default: On
How to use it: Click the switch to turn it on (blue) or off.
When to use it: Keep on for desktop visitors.
Example: On.
Result: Arrows at the sides.

Dots

What it does: Shows a dot per page below the slides.
What to enter or choose: On or off.
Default: On
How to use it: Click the switch to turn it on (blue) or off.
When to use it: To show how many slides there are.
Example: On.
Result: Clickable dots.

Loop

What it does: After the last slide, continues from the first.
What to enter or choose: On or off.
Default: On
How to use it: Click the switch to turn it on (blue) or off.
When to use it: Usually on.
Example: On.
Result: Arrows never become disabled.

Autoplay

What it does: Advances slides automatically.
What to enter or choose: On or off.
Default: Off
How to use it: Click the switch to turn it on (blue) or off.
When to use it: Use sparingly — moving content distracts.
Example: On for a hero slider.
Result: Pauses on hover and focus, shows a pause button, and never runs for visitors who prefer reduced motion.

Delay (seconds)Shown when Autoplay is on

What it does: Time each slide stays.
What to enter or choose: A number from 2 to 15 (s).
Default: 5 seconds
How to use it: Drag the slider, or type a number in the box next to it.
When to use it: Longer for slides with text.
Example: 6.
Result: Slower or faster autoplay.

Design & styling

Select the block, open the Styles tab in the settings sidebar (the half-filled circle icon next to the gear) and use the three pickers at the top of the Style panel:

Element — which part of the block to style.
State — Normal, or a state such as Hover (only the states the part supports are offered).
Device — Desktop, Tablet or Mobile, for values that can differ per screen size.

Only panels that make sense for the chosen part and state are shown. The full meaning of every control is in the Styling Controls guide; below is exactly what Products offers.

Element: Card selected first

Each product card. Hover state.

Styles-tab controls for “Card”
Panel	Control	Per device	Available in states
Background	Type	—	Normal, Hover
	Color / Gradient	—	Normal, Hover
	Image	—	Normal
Border	Border type	—	Normal, Hover
	Border	—	Normal, Hover
	Radius	Yes	Normal
Box Shadow	Remove shadow	—	Normal, Hover
Box Shadow	Shadow layers	—	Normal, Hover
Spacing	Margin	Yes	Normal
Spacing	Padding	Yes	Normal
Sizing	Width	Yes	Normal
	Max width	Yes	Normal
	Height	Yes	Normal
	Min width / Min height / Max height	Yes	Normal
Effects	Opacity (%)	Yes	Normal, Hover

States for this part:

Hover — When the mouse pointer is over it. (Touch screens have no hover; they show the normal style.)

Element: Block

The whole block.

Styles-tab controls for “Block”
Panel	Control	Per device	Available in states
Background	Type	—	Normal
	Color / Gradient	—	Normal
	Image	—	Normal
Border	Border type	—	Normal
	Border	—	Normal
	Radius	Yes	Normal
Box Shadow	Remove shadow	—	Normal
Box Shadow	Shadow layers	—	Normal
Spacing	Margin	Yes	Normal
Spacing	Padding	Yes	Normal
Sizing	Width	Yes	Normal
	Max width	Yes	Normal
	Height	Yes	Normal
	Min width / Min height / Max height	Yes	Normal
	Block alignment	Yes	Normal
Position	Position	Yes	Normal
	Top / Right / Bottom / Left	Yes	Normal
	Z-index	Yes	Normal
	Overflow	Yes	Normal
Transform	Move X / Move Y	—	Normal
	Scale X / Scale Y	—	Normal
	Rotate (°), Rotate X (°), Rotate Y (°)	—	Normal
	Skew X (°) / Skew Y (°)	—	Normal
Effects	Opacity (%)	Yes	Normal
	State transition (ms)	—	Normal
	Timing	—	Normal
Visibility	Show on Desktop / Tablet / Mobile	—	Normal

States: Normal only.

Element: Image

The image area. Hover state (card hovered).

Styles-tab controls for “Image”
Panel	Control	Per device	Available in states
Background	Type	—	Normal, Hover
	Color / Gradient	—	Normal, Hover
	Image	—	Normal
Border	Radius	Yes	Normal
Effects	Opacity (%)	Yes	Normal, Hover

States for this part:

Hover — When the mouse pointer is over the whole block — so this part changes as soon as visitors point at the block.

Element: Sale badge

The sale badge.

Styles-tab controls for “Sale badge”
Panel	Control	Per device	Available in states
Typography	Font family	—	Normal
	Font size	Yes	Normal
	Weight	—	Normal
	Style	—	Normal
	Line height	Yes	Normal
	Letter spacing	Yes	Normal
	Letter case	—	Normal
	Alignment	Yes	Normal
	Decoration	—	Normal
Colors	Text	—	Normal
Background	Type	—	Normal
	Color / Gradient	—	Normal
	Image	—	Normal
Border	Radius	Yes	Normal
Spacing	Padding	Yes	Normal

States: Normal only.

Element: Category

The category line.

Styles-tab controls for “Category”
Panel	Control	Per device	Available in states
Typography	Font family	—	Normal
	Font size	Yes	Normal
	Weight	—	Normal
	Style	—	Normal
	Line height	Yes	Normal
	Letter spacing	Yes	Normal
	Letter case	—	Normal
	Alignment	Yes	Normal
	Decoration	—	Normal
Colors	Text	—	Normal

States: Normal only.

Element: Title

Product names. Hover state (card hovered).

Styles-tab controls for “Title”
Panel	Control	Per device	Available in states
Typography	Font family	—	Normal
	Font size	Yes	Normal
	Weight	—	Normal
	Style	—	Normal
	Line height	Yes	Normal
	Letter spacing	Yes	Normal
	Letter case	—	Normal
	Alignment	Yes	Normal
	Decoration	—	Normal, Hover
Colors	Text	—	Normal, Hover

States for this part:

Hover — When the mouse pointer is over the whole block — so this part changes as soon as visitors point at the block.

Element: Price

The price.

Styles-tab controls for “Price”
Panel	Control	Per device	Available in states
Typography	Font family	—	Normal
	Font size	Yes	Normal
	Weight	—	Normal
	Style	—	Normal
	Line height	Yes	Normal
	Letter spacing	Yes	Normal
	Letter case	—	Normal
	Alignment	Yes	Normal
	Decoration	—	Normal
Colors	Text	—	Normal

States: Normal only.

Element: Button

The add-to-cart button. Hover and Focus.

Styles-tab controls for “Button”
Panel	Control	Per device	Available in states
Typography	Font family	—	Normal
	Font size	Yes	Normal
	Weight	—	Normal
	Style	—	Normal
	Line height	Yes	Normal
	Letter spacing	Yes	Normal
	Letter case	—	Normal
	Alignment	Yes	Normal
	Decoration	—	Normal, Hover, Focus
Colors	Text	—	Normal, Hover, Focus
Background	Type	—	Normal, Hover, Focus
	Color / Gradient	—	Normal, Hover, Focus
	Image	—	Normal
Border	Border type	—	Normal, Hover, Focus
	Border	—	Normal, Hover, Focus
	Radius	Yes	Normal
	Focus indicator	—	Focus
Box Shadow	Remove shadow	—	Normal, Hover, Focus
Box Shadow	Shadow layers	—	Normal, Hover, Focus
Spacing	Padding	Yes	Normal
Sizing	Width	Yes	Normal
	Max width	Yes	Normal
	Height	Yes	Normal
	Min width / Min height / Max height	Yes	Normal
Effects	Opacity (%)	Yes	Normal, Hover, Focus

States for this part:

Hover — When the mouse pointer is over it. (Touch screens have no hover; they show the normal style.)
Focus — When it has keyboard focus — reached with the Tab key. Mouse clicks usually do not show focus styles.

Element: Carousel arrows

Carousel arrows.

Styles-tab controls for “Carousel arrows”
Panel	Control	Per device	Available in states
Colors	Text	—	Normal, Hover, Focus
Background	Type	—	Normal, Hover, Focus
	Color / Gradient	—	Normal, Hover, Focus
	Image	—	Normal
Border	Border type	—	Normal, Hover, Focus
	Border	—	Normal, Hover, Focus
	Radius	Yes	Normal
Box Shadow	Remove shadow	—	Normal, Hover, Focus
Box Shadow	Shadow layers	—	Normal, Hover, Focus
Sizing	Width	Yes	Normal
	Max width	Yes	Normal
	Height	Yes	Normal
	Min width / Min height / Max height	Yes	Normal

States for this part:

Hover — When the mouse pointer is over it. (Touch screens have no hover; they show the normal style.)
Focus — When it has keyboard focus — reached with the Tab key. Mouse clicks usually do not show focus styles.

Element: Carousel dots

Carousel dots. Active = current slide.

Styles-tab controls for “Carousel dots”
Panel	Control	Per device	Available in states
Background	Type	—	Normal, Active
	Color / Gradient	—	Normal, Active
	Image	—	Normal
Border	Radius	Yes	Normal
Sizing	Width	Yes	Normal
	Max width	Yes	Normal
	Height	Yes	Normal
	Min width / Min height / Max height	Yes	Normal

States for this part:

Active — The selected / current item ([aria-current="true"]).

Responsive settings

Brigade Blocks uses three screen sizes: Desktop (wider than 1023px), Tablet (600–1023px) and Mobile (599px and narrower). Tablet and Mobile values are optional: when empty, the value of the next larger screen is used.

In the Styles tab, pick the Device first; these controls can then have a different value for that screen size: Radius, Margin, Padding, Width, Max width, Height, Min width / Min height / Max height, Opacity (%), Block alignment, Position, Top / Right / Bottom / Left, Z-index, Overflow, Font size, Line height, Letter spacing, Alignment.

The Visibility panel (Styles tab, Normal state) can hide the block entirely on Desktop, Tablet or Mobile.

Advanced options

HTML anchor (Advanced section of the Settings tab) — a unique name such as pricing, so you can link straight to this block with #pricing at the end of the page address (for example from a menu).
Additional CSS class(es) (Advanced section) — for custom CSS from your theme or the Site Editor. Separate several classes with spaces.
Custom attributes (Advanced section) — add data-*, title, aria-label, aria-describedby, lang or dir attributes. See Custom attributes.
State transition (Styles tab → Effects, Normal state) — how smoothly hover and focus styles animate.
Width alignment (block toolbar) — Wide width, Full width, when your theme supports them.

How it works on your site

Products are rendered on the server with WooCommerce’s own prices, badges and add-to-cart buttons (AJAX add to cart works as usual). Only visible, published products are listed.

Accessibility

Add-to-cart buttons have WooCommerce’s descriptive labels (“Add “Blue Hoodie” to your cart”).
Carousels follow the shared accessible carousel rules (keyboard arrows and dots, pause button, reduced motion respected).

Limitations and notes

Up to 24 products.
Related, Upsells and Cross-sells need the right context (a product page or a cart).

Troubleshooting

The block is empty on the site.

No product matches. For Related/Upsells, make sure the block is in the single product template; for Cross-sells, add products with cross-sells to the cart.