← All posts

Custom Gutenberg Block Styles: Overlapping Gallery in FanCoolo WP

fancoolo

Custom Gutenberg block styles let you change how a core block looks without building a custom block. In this video we register a FanCoolo WP style called stack gallery for the core Gallery block, then use nested SCSS to turn it into a row of round, overlapping images. Editors keep the normal Gallery block, so adding, removing and reordering images works the way it always has.

Why block styles matter

Many core blocks already come with styles. Select an Image block, open the Styles tab in the block sidebar, and you get Default and Rounded. Picking one adds a class (is-style- plus the style name) to the block, and your CSS targets that class. That's the whole mechanism.

So when you only need a visual variant of a block that already exists, a style is often enough. The block keeps its editing experience, and you add a class and some CSS.

Set up the core Gallery block

  1. Add a Gallery block and pick images from the Media Library (the video uses nine portraits).
  2. In the block settings, keep Resolution at Large.
  3. Turn on Crop images to fit.
  4. Set Aspect ratio to Square - 1:1. The images will be round and overlapping, so they need to be square.
  5. Set Columns. You can also set Block spacing to zero, but you don't have to, because the style overrides it.
  6. Save the page.

The Gallery block is a wrapper around core Image blocks, so its settings apply to every image inside it.

Register a custom FanCoolo style

At this point the Gallery block's Styles panel has no custom styles. To add one:

  1. In FanCoolo WP, open the Styles tab and click Add new.
  2. Name it stack gallery. FanCoolo creates the starting selector .is-style-stack-gallery {} for you.
  3. Under Assigned Blocks → Block Types, add core/gallery. The field accepts any block name, such as core/paragraph or core/heading.
  4. Click Save and reload the editor.

Now, when you select the Gallery block, stack gallery shows up under Styles next to Default. Selecting it doesn't change anything yet because there's no CSS.

Inspect the Gallery's DOM structure

Open the page on the front end and inspect it with DevTools. The structure is simple:

  • an outer figure.wp-block-gallery that has the is-style-stack-gallery class
  • a figure.wp-block-image for each image
  • an img inside each of those figures

The outer gallery is already a flex container. So the main job is to stop it wrapping and control the size of each image.

Write nested SCSS for the structure

FanCoolo compiles SCSS, so you can write selectors nested the same way the HTML is:

.is-style-stack-gallery {

  figure {

    img {

    }

  }

}

The editor is Monaco (the editor from Visual Studio Code) with Emmet built in. You get CSS autocomplete as you type, and Cmd+D selects the next match for multi-cursor editing.

Round and fix the image size

  1. Add flex-wrap: nowrap !important; to the gallery so the images stay on one row.
  2. On img, add border-radius: 1000px; to make the images round.
  3. Give the images a fixed width and height so they stop resizing.
  4. Add gap: 0 !important; to the gallery. The !important covers the case where someone changed the block spacing in the block settings.

The image was still rendering at a different size, so max-width and then !important were added on the image to force it.

Debug layout with colored borders

To see what each level is doing, give every level a different colored border:

.is-style-stack-gallery {
  flex-wrap: nowrap !important;
  gap: 0 !important;

  border: 2px solid red;

  figure {
    border: 2px solid green;

    img {
      border: 2px solid yellow;
      border-radius: 1000px;
      max-width: 30px;
      height: 30px;
    }
  }
}

This showed that each figure was much wider than its image. Setting max-width on the figure to the image width fixes that.

A reusable image-size variable

The same size value was now in several places, so it moved into a custom property on the style class: --img-size: 30px;. Because it's scoped to .is-style-stack-gallery, it won't clash with an --img-size variable defined anywhere else on the site. With var(--img-size) used everywhere, changing the size is a single edit. The value was then raised to 60px.

Overlap with a negative margin

To overlap the images, give each figure a negative left margin based on the same variable:

margin-left: calc(var(--img-size) * -0.3) !important;

Fix the first image with :first-child

The negative margin also pushes the first image outside the container. Reset it for the first figure:

&:first-child {
  margin-left: 0 !important;
}

Once the layout was correct, the debug borders came off, and the image got a white border and a box shadow.

Fine-tune box-shadow in DevTools

Start with a placeholder shadow such as box-shadow: 0px 0px 0px black;. Then adjust it in DevTools, where you can edit the offsets and blur and pick the color with the color picker. When it looks right, copy the value back into FanCoolo. In a real project you'd usually use your color variables here, but this is a fast way to get the values.

Here is the final style from the video:

.is-style-stack-gallery {

  --img-size: 60px;

  flex-wrap: nowrap !important;
  gap: 0 !important;

  figure {
    max-width: var(--img-size) !important;
    margin-left: calc(var(--img-size) * -0.3) !important;

    &:first-child {
      margin-left: 0 !important;
    }

    img {
      border: 2px solid white;
      box-shadow: 3px 4px 8px #003eca;
      border-radius: 1000px;
      width: var(--img-size) !important;
      height: var(--img-size) !important;
    }
  }
}

Full editor UX kept: drag, drop, add images

The stacked gallery looks the same in the Gutenberg editor as on the front end. Editors can drag images to reorder them or use Add to put more images in the gallery, and the style applies to the new ones automatically.

To get this with a custom block, you'd probably need two blocks (a wrapper and an image). You'd also lose the Gallery block's quick multi-image upload, or you'd have to build a custom sidebar to manage the images. With a block style, editors choose stack gallery and everything else stays the same.

FAQ

What is a Gutenberg block style? A block style is a named variant of an existing block. When an editor selects it in the Styles panel, WordPress adds an is-style-{name} class to the block, and your CSS targets that class. The block's markup and editing controls don't change.

How do I add a custom block style to a core block with FanCoolo WP? In FanCoolo, go to Styles → Add new and name the style. Under Assigned Blocks → Block Types, add the block name (for example core/gallery), then write your CSS or SCSS for the generated .is-style-… class and save. The style then appears in the block's Styles panel.

Can I write SCSS in FanCoolo styles? Yes. Styles are compiled as SCSS, so you can nest selectors, use &:first-child, and use CSS custom properties. The editor is Monaco with Emmet autocomplete.

Why use a block style instead of building a custom gallery block? The core Gallery block already handles multi-image upload, drag-and-drop ordering and cropping. A style only changes how it looks, so editors keep the interface they already know and you don't have to rebuild those features.

Which FanCoolo version has block styles? In the video, Marko says block styles are coming in FanCoolo WP version 1.3.

Get FanCoolo WP → dplugins.com

Related posts