Cogio Card Blocks

Current version: 1.0.0

Introduction

Cogio Card Blocks is a WordPress plugin for creating responsive grids of fully clickable cards using the Gutenberg block editor. It was created to overcome the limitations of existing Gutenberg blocks in creating fully clickable calls to action.

The plugin adds two blocks:

• Cogio Card Grid
• Cogio Card

The Card Grid block controls the overall layout, including the number of columns displayed at different screen sizes, the space between cards and whether all cards should match the height of the tallest card in the grid.

Each Cogio Card contains its own image or icon, heading, body text and optional Call To Action text. The whole card can be linked to another page, post or external website.

The plugin is designed to provide a consistent card-building experience without requiring users to assemble multiple Group, Image, Heading, Paragraph and Button blocks manually.

Features

Cogio Card Blocks currently includes the following features:

• Responsive Card Grid block
• Individual Cogio Card blocks
• Configurable desktop, tablet and mobile column counts
• Adjustable space between cards
• Optional equal-height cards across the entire grid
• Fully clickable cards
• Optional opening of links in a new browser tab
• Optional accessible link labels
• Direct editing of card content within the block editor
• Selectable heading levels from H2 to H6
• Bold and italic formatting for headings, body text and Call To Action text
• Independent alignment controls for:
  • headings
  • body text
  • Call To Action text
• Image and Icon display modes
• Image selection, replacement and removal from within the card
• WordPress image size selection
• Image aspect ratio controls
• Image fit and position controls
• Adjustable icon size and alignment
• Image alternative text drawn from the WordPress Media Library
• Optional Call To Action icons
• Card background and text colour controls
• Card margin and padding controls
• Border width, style, colour and radius controls
• Shadow controls
• Multiple hover effects
• Keyboard focus styling
• Reduced-motion support

Guides

Adding a Card Grid

Open the page or post where you want the cards to appear.

Select the block inserter and search for:

Cogio Card Grid

Add the block to the page.

A new Card Grid initially contains three Cogio Card blocks. Additional cards can be added using the plus button shown within the grid.

Cards can also be duplicated, moved or removed using the standard WordPress block controls.

Selecting the Card Grid

To edit the grid rather than an individual card, select the outer Cogio Card Grid block.

The Card Grid can be selected using:

• the block breadcrumb shown at the bottom of the editor
• the List View
• the Select parent block option in the block toolbar

The Card Grid settings appear in the block settings sidebar.

Card Grid Settings

Desktop Columns

The Desktop columns setting controls how many cards appear in each row on larger screens.

The available values are between one and six columns.

For example:

• One column displays each card across the available width.
• Two columns display two cards per row.
• Three columns display three cards per row.
• Four or more columns create more compact card layouts.

The most suitable value depends on the width of the page and the amount of content inside each card.

Tablet Columns

The Tablet columns setting controls how many cards appear per row on medium-width screens.

The available values are between one and four columns.

A common configuration is:

Desktop: 3
Tablet: 2
Mobile: 1

This displays three cards per row on larger screens, two cards per row on tablets and one card per row on smaller mobile screens.

Mobile Columns

The Mobile columns setting controls how many cards appear per row on small screens.

The available options are:

• One column
• Two columns

One column is recommended for cards containing longer headings, body text or larger images.

Two columns may be useful for compact cards containing short labels or icons.

Gap Between Cards

The Gap between cards setting controls the horizontal and vertical space between cards.

The value is set in pixels.

A larger value creates more space between cards, while a smaller value produces a tighter grid.

Equal Height Cards

Enable Equal height cards to make every card in the grid match the height of the tallest card.

This applies across the entire grid, rather than only matching cards within the same row.

The height is recalculated when:

• the page first loads
• card images finish loading
• the browser window changes size

This helps maintain a consistent design when cards contain different amounts of content or when the grid wraps onto multiple rows.

Disable Equal height cards if each card should use only the height required by its own content.

Grid Alignment

The Card Grid supports the standard WordPress wide and full-width alignment options where these are supported by the active theme.

The available alignment options may depend on the theme and the width of the surrounding page template.

Grid Spacing and Background

The Card Grid supports WordPress spacing and background controls.

These can be used to add:

• margin around the grid
• padding inside the grid
• a background colour behind the complete set of cards

Adding and Editing Cards

Each Cogio Card is placed inside a Cogio Card Grid.

Select an individual card to edit its content or settings.

The following content can be edited directly inside the card:

• image or icon
• heading
• body text
• Call To Action text

Other card settings are available in the block settings sidebar.

Adding More Cards

Select the plus button within the Card Grid and choose Cogio Card.

The Card Grid only accepts Cogio Card blocks as its direct children.

Duplicating a Card

To reuse an existing card design:

1. Select the card.
2. Open the block options menu.
3. Select Duplicate.
4. Update the duplicated card’s image, text and link.

Duplicating a card also copies its current design settings, including its border, colours, image mode and hover effect.

Moving Cards

Cards can be reordered using:

• the move left and move right controls
• drag and drop
• the WordPress List View

Card Links

Link URL

The Link URL setting controls where the visitor is taken when they select the card.

The link can point to:

• a page on the same website
• a blog post
• a product
• a document
• an external website
• another valid URL

Internal links can be entered as a relative path:

/services/web-design/

A full URL can also be used:

https://example.com/

When a Link URL is supplied, the complete card becomes clickable.

If no Link URL is supplied, the card is displayed as a non-clickable content container.

Open in New Tab

Enable Open in new tab to open the card link in a separate browser tab.

This may be suitable for links to external websites or documents.

Links to pages within the same website would normally remain in the same tab.

Accessible Label

The Accessible label setting provides an optional description of the card link for screen readers.

In most cases, this should be left empty because the visible card heading and text already describe the destination.

An accessible label may be useful when the visible content does not clearly explain where the link leads.

Avoid using an accessible label that conflicts with the visible wording of the card.

Card Heading

Editing the Heading

Select the heading text directly within the card and begin typing.

The heading supports:

• bold
• italic
• left alignment
• centre alignment
• right alignment

The heading alignment controls appear in the block toolbar while the heading field is selected.

Heading Type

The Heading type setting controls the HTML heading level used by the card.

The available options are:

• H2
• H3
• H4
• H5
• H6

The selected heading type should follow the structure of the surrounding page.

For example, if a card grid appears beneath an H2 section heading, the card headings would normally use H3.

Heading levels should be selected based on the structure and meaning of the page rather than their visual size.

The plugin applies consistent card heading styling regardless of the selected heading type.

Card Body Text

Select the body text directly within the card to edit it.

The body text supports:

• bold
• italic
• left alignment
• centre alignment
• right alignment

The alignment controls appear in the block toolbar while the body text field is selected.

Body text should normally provide a short description of the page, service or resource represented by the card.

Call To Action

Call To Action Text

The Call To Action field appears at the bottom of the card.

Select the field directly within the card and enter wording such as:

Find out more

View services

Read the guide

Explore the project

The Call To Action is part of the overall card link. It is not a separate button or separate link.

Leaving the field empty removes the Call To Action text from the front end.

Call To Action Alignment

Select the Call To Action text and use the alignment controls in the block toolbar.

The available options are:

• Left
• Centre
• Right

Call To Action Icon

The CTA icon setting adds an optional symbol to the right of the Call To Action text.

The available options are:

• None
• Rightwards arrow
• Chevron
• Long rightwards arrow
• Heavy wide-headed rightwards arrow
• Heavy rightwards arrow

The icon moves slightly to the right when the card is hovered over or receives keyboard focus.

Select None to display Call To Action text without an icon.

Card Images

Choosing an Image

When a card does not yet have an image, select Choose image inside the card.

This opens the WordPress Media Library, where you can:

• select an existing image
• upload a new image
• review the image’s Media Library details

Once selected, the image is displayed directly inside the card editor.

Replacing an Image

Select Replace image from the controls displayed over the image.

Choose a different image from the Media Library or upload a new file.

Removing an Image

Select Remove image from the controls displayed over the image.

Removing an image does not remove the original file from the WordPress Media Library.

Image Alternative Text

The plugin uses the alternative text stored against the image in the WordPress Media Library.

To update the alternative text:

1. Open the WordPress Media Library.
2. Select the relevant image.
3. Update the Alternative Text field.
4. Save the change.

The updated alternative text will then be used by the card without requiring the card itself to be edited.

Decorative images may use empty alternative text where appropriate.

Image Display Modes

The Image display setting controls how the selected image is presented.

The available modes are:

• Image
• Icon

Image Mode

Use Image mode for traditional card images, photographs, banners and illustrations.

Images in this mode can use:

• selectable WordPress image sizes
• aspect ratios
• Cover or Contain fitting
• image positioning

The image normally spans the available width of the card.

Icon Mode

Use Icon mode for smaller graphics, logos and uploaded icons.

Images in Icon mode:

• retain their proportions
• are not cropped
• do not stretch to fill the card width
• can use a custom display size
• can be aligned left, centre or right

Icon mode is suitable for small SVG, PNG, WebP or other supported image files representing services, features or categories.

Whether a particular file type can be uploaded depends on the WordPress configuration and permitted Media Library file types.

Image Settings

Image Size

The Image size setting controls which WordPress-generated version of an image is loaded.

The available options are:

• Thumbnail
• Medium
• Large
• Full

Large is the default setting.

Using an appropriately sized image can reduce unnecessary page loading time.

Thumbnail or Medium may be suitable for compact cards. Large is normally suitable for full-width card images. Full loads the original uploaded image and should be used carefully with very large files.

The visible dimensions of the image are still controlled by the card layout and image display settings.

Image Aspect Ratio

The Image aspect ratio setting is available in Image mode.

The available options are:

• Auto
• Square
• 4:3
• 16:9
• 21:9

Auto uses the natural proportions of the image.

The other options create a consistent image area across cards, even when the original image dimensions differ.

When an aspect ratio is selected, part of the image may be cropped if Image fit is set to Cover.

Image Fit

The Image fit setting is available in Image mode.

The available options are:

• Cover
• Contain

Cover

Cover fills the entire image area.

Parts of the image may be cropped when its proportions do not match the selected aspect ratio.

This is normally the most suitable option for photographs and card thumbnails.

Contain

Contain keeps the complete image visible inside the image area.

Empty space may appear around the image if its proportions do not match the selected aspect ratio.

This may be more suitable for illustrations, product images, diagrams or graphics that should not be cropped.

Image Position

The Image position setting controls which area of an image remains most visible when Cover fitting crops the image.

The available options are:

• Centre
• Top
• Bottom
• Left
• Right

For example, select Top when the important subject appears near the upper part of the photograph.

Image position may have little visible effect when:

• Image fit is set to Contain
• the image uses its natural aspect ratio
• the source image already matches the selected aspect ratio

Icon Size

The Icon size setting appears when Icon mode is selected.

The size can be adjusted between 24 and 200 pixels.

The selected value sets the maximum width and height of the icon while preserving its natural proportions.

Icon Alignment

The Icon alignment setting appears when Icon mode is selected.

The available options are:

• Left
• Centre
• Right

This controls the horizontal position of the icon within the card.

Card Colours and Spacing

Cogio Cards support standard WordPress block design controls.

Depending on the active theme and WordPress configuration, these may include:

• text colour
• background colour
• margin
• padding
• shadow

Text Colour

The Text colour control changes the colour of the card heading, body text and Call To Action.

The card link retains the selected card text colour when hovered, focused or active.

Background Colour

The Background colour control changes the card’s background.

Choose a combination that maintains sufficient contrast between the background and text.

Padding

Padding creates space inside the outer card.

The card uses border-box sizing so padding is included within its calculated dimensions and does not cause the card to overflow the grid.

The card content area also contains its own standard internal spacing.

Margin

Margin adds space around an individual card.

In most cases, the Card Grid gap setting should be used to create consistent space between cards.

Individual card margins may be useful for unusual layouts but can make spacing within a grid inconsistent.

Shadow

The Shadow control applies a persistent shadow to the card.

This is separate from the Shadow and Lift and shadow hover effects, which only become visible when the card is hovered over or receives keyboard focus.

Card Border

The Card border panel provides independent border controls for each card.

Border Width

The Border width setting controls the thickness of the card border.

The available range is from 0 to 20 pixels.

Set the width to 0 to remove the visible border without changing the other stored border settings.

Border Style

The available border styles are:

• None
• Solid
• Dashed
• Dotted
• Double

Selecting None prevents the border from being displayed.

Border Colour

The Border colour control changes the normal card border colour.

The available colour choices may include colours supplied by the active theme.

Border Radius

The Border radius setting rounds the outside corners of the card.

The available range is from 0 to 100 pixels.

A value of 0 creates square corners. Increasing the value creates progressively more rounded corners.

Images are clipped to the card shape because the card hides overflowing content.

Hover Effects

The Hover effect setting controls the visual response when a visitor moves a pointer over a linked card or focuses it using a keyboard.

The available effects are:

• None
• Lift
• Shadow
• Lift and shadow
• Image zoom
• Border highlight
• Background tint

None

No additional hover animation is applied.

The normal keyboard focus outline remains available.

Lift

The card moves slightly upwards.

Shadow

A shadow appears around the card.

Lift and Shadow

The card moves slightly upwards and displays a shadow.

Image Zoom

The card image increases slightly in size within its image container.

The image remains clipped to the card image area.

This effect also works with Icon mode, although it may be more noticeable with traditional images.

Border Highlight

An additional outline appears around the outside of the card using the current text colour.

This effect does not replace the card’s normal border.

Background Tint

A subtle tint is displayed over the card.

Reduced Motion

The plugin respects the visitor’s reduced-motion browser or operating-system preference.

When reduced motion is requested, animated transformations and transitions are disabled or reduced.

How Equal Heights Work

Standard CSS Grid layouts normally match card heights only within each row.

Cogio Card Blocks includes a small front-end script that can match every card in a grid to the tallest card across all rows.

When Equal height cards is enabled, the plugin:

1. finds the cards directly inside each Card Grid
2. clears previously calculated minimum heights
3. measures the natural height of every card
4. identifies the tallest card
5. applies that minimum height to every card in the grid

Each Card Grid is calculated independently.

The plugin recalculates heights after images load and when the browser window is resized.

If JavaScript is unavailable, the grid remains usable and cards continue to stretch to match other cards within their own CSS Grid row.

Accessibility

Semantic Headings

Card headings use real HTML heading elements from H2 to H6.

Choose heading levels that follow the logical structure of the surrounding page.

Card Links

When a Link URL is supplied, the card is rendered as a standard HTML link.

This means the card can be:

• selected with a pointer
• reached using the Tab key
• opened using the Enter key
• identified as a link by assistive technology

Keyboard Focus

Linked cards display a visible focus outline when reached using a keyboard.

Hover effects are also applied to keyboard focus where appropriate.

Alternative Text

Image alternative text is managed through the WordPress Media Library.

Alternative text should describe the meaning or purpose of an informative image rather than simply naming the file.

Decorative images should normally have empty alternative text.

Accessible Link Labels

Use the optional Accessible label only when the visible card content does not describe the destination clearly.

Colour Contrast

When changing card text, background and border colours, make sure the resulting combinations remain easy to read.

Troubleshooting

Cards Only Match Height Within Each Row

Check that Equal height cards is enabled on the parent Card Grid.

If the option is enabled but cards still only match within individual rows, check:

1. The front-end JavaScript file is loading.
2. The browser console does not contain JavaScript errors.
3. A caching or optimisation plugin is not delaying or removing the script.
4. The cards are direct children of the Cogio Card Grid.
5. The website and browser caches have been cleared.

Without JavaScript, CSS Grid can only guarantee matching heights within each row.

Cards Overlap Content Below the Grid

Make sure the plugin is running version 1.0.0 or later.

The current version uses natural grid stretching and minimum heights rather than forcing cards to use height: 100%.

Also check whether the active theme applies fixed heights, negative margins or absolute positioning to the card or grid classes.

Padding Causes a Card to Overflow

Cogio Card Blocks uses border-box sizing so padding should remain within the card’s calculated dimensions.

If overflow occurs, check whether the active theme overrides:

box-sizing: border-box;

Also check whether custom CSS applies a fixed width or height to the card.

Icon Padding Causes Horizontal Overflow

The icon image wrapper uses border-box sizing so its padding is included within its width.

If an icon still overflows, check whether theme CSS overrides the image wrapper’s box sizing or applies additional width, margin or padding.

An Image Is Cropped Incorrectly

Check the following settings:

1. Image aspect ratio.
2. Image fit.
3. Image position.

Use Cover when the image should fill the available area.

Use Contain when the entire image needs to remain visible.

Adjust Image position to keep the important part of the image visible when Cover crops it.

An Image Looks Blurred

Check the Image size setting.

Thumbnail or Medium may be too small for a wide card. Change the setting to Large or Full.

Also check the dimensions and quality of the original uploaded image.

An Image Is Loading at an Unnecessarily Large Size

Change the Image size setting from Full to Large or Medium.

The visible size of the image may be much smaller than the original uploaded file.

The Image Alternative Text Is Wrong

Open the image in the WordPress Media Library and update its Alternative Text field.

The card does not store a separate copy of the alternative text.

Icon Mode Still Looks Like a Full-Width Image

Check that Image display is set to Icon.

Also clear any page, browser or optimisation cache after updating the setting.

The Card Is Not Clickable

Select the individual card and check that a valid Link URL has been entered.

A card without a Link URL is intentionally rendered as a non-clickable container.

The Link Opens in the Wrong Tab

Check the Open in new tab setting within the Card link panel.

Disable it for normal internal website links.

Enable it where opening a separate tab is appropriate.

The Call To Action Does Not Have an Icon

Check the CTA icon setting in the Call To Action panel.

Selecting None intentionally removes the icon.

The Call To Action text can still appear without an icon.

The Call To Action Alignment Is Not Changing

Select the Call To Action text directly inside the card before using the alignment toolbar.

The toolbar applies alignment to the currently selected card text area:

• heading
• body text
• Call To Action

The Heading Uses the Wrong HTML Level

Select the card and open the Heading panel.

Choose the required heading type from H2 to H6.

The visual appearance remains consistent, but the underlying HTML element changes.

Border Settings Are Not Visible

Check that:

1. Border style is not set to None.
2. Border width is greater than 0.
3. Border colour contrasts with the card background.
4. Theme CSS is not overriding the card border declaration.

Border Radius Is Not Visible

A border radius may be difficult to see when:

• the value is very small
• the card and surrounding background use the same colour
• no border is displayed
• the image or card background does not reach the card edges

Increase the radius temporarily to confirm that the setting is being applied.

Hover Effects Are Not Working

Check that:

1. A Link URL has been supplied.
2. The pointer is over the card itself.
3. Reduced motion is not enabled.
4. Theme CSS is not overriding transforms, shadows or pseudo-elements.
5. Cached CSS has been cleared.

Some effects may still apply to a non-linked card in the editor preview, but hover effects are primarily intended for clickable cards on the front end.

Changes Are Not Showing Immediately

Clear:

• the browser cache
• any WordPress caching plugin
• server-side page caching
• CSS or JavaScript optimisation caches
• a content delivery network cache, where applicable

The plugin versions its CSS and JavaScript files using their modification times, but other caching systems may still retain older page output or combined asset files.