Skip to main content
The Grid layout displays portfolio items in a traditional grid structure with consistent row heights. Perfect for galleries where uniform appearance is important.

​
Overview

Grid is a classic layout option that arranges items in rows and columns with consistent heights. Unlike Masonry, which allows variable heights, Grid ensures all items in a row have the same height, creating a clean, organized appearance.

​
Key Features

  • Consistent row heights: All items in a row have equal height
  • Flexible columns: Configure 1-6+ columns
  • Custom layout mode: Uses a custom Isotope layout mode (vpRows)
  • Responsive design: Automatically adjusts for different screen sizes
  • FireFox compatibility: Custom implementation fixes grid positioning issues in FireFox

​
Configuration Options

​
Columns

​
gridColumns
number
default:"3"
Number of columns to display in the grid. Automatically adjusts for smaller screens.
Recommended values:
  • 2 - Two columns (large previews)
  • 3 - Three columns (default, balanced)
  • 4 - Four columns (compact)
  • 5 - Five columns (dense grid)
  • 6+ - Six or more columns (thumbnail view)

​
Image Aspect Ratio

​
gridImagesAspectRatio
string
Force all images to a specific aspect ratio for perfect uniformity.
Common ratios:
  • 16:9 - Widescreen (1.77:1)
  • 4:3 - Standard (1.33:1)
  • 1:1 - Square
  • 3:2 - Classic photo (1.5:1)
  • 21:9 - Ultra-wide (2.33:1)
For the most uniform appearance, combine Grid layout with a fixed aspect ratio. This ensures every item has identical dimensions.

​
Custom Grid Layout Mode

Visual Portfolio implements a custom Isotope layout mode called vpRows that fixes grid positioning issues, particularly in FireFox: 
// Custom vpRows layout mode
const VPRows = window.Isotope.LayoutMode.create('vpRows');

proto._getItemLayoutPosition = function (item) {
  item.getSize();
  
  // Calculate column span
  const remainder = item.size.outerWidth % this.columnWidth;
  const mathMethod = remainder && remainder < 1 ? 'round' : 'ceil';
  let colSpan = Math[mathMethod](item.size.outerWidth / this.columnWidth);
  
  // Position in grid
  let col = this.horizontalColIndex % this.cols;
  const isOver = colSpan > 1 && col + colSpan > this.cols;
  col = isOver ? 0 : col;
  
  return { x: this.x, y: this.y };
};

​
Implementation Details

​
JavaScript Initialization

The Grid layout is initialized in /assets/js/layout-grid.js: 
// Set column width
self.addStyle('.vp-portfolio__item-wrap', {
  width: `${100 / self.options.gridColumns}%`,
});

// Change Isotope layout mode to custom vpRows
initOptions.layoutMode = 'vpRows';

​
Responsive Columns

The layout automatically adjusts columns based on screen size: 
// Calculate responsive breakpoints
let count = self.options.gridColumns - 1;
let currentPoint = Math.min(screenSizes.length - 1, count);

for (; currentPoint >= 0; currentPoint -= 1) {
  if (count > 0) {
    self.addStyle('.vp-portfolio__item-wrap', {
      width: `${100 / count}%`,
    }, `screen and (max-width: ${screenSizes[currentPoint]}px)`);
  }
  count -= 1;
}

​
Responsive Behavior

Automatic column reduction:
  • Large Desktop (>1920px): Full column count
  • Desktop (1200-1920px): Full column count
  • Tablet (768-1199px): Columns - 1
  • Mobile (480-767px): Columns - 2
  • Small Mobile (<480px): 1 column

​
Usage Examples

​
Basic Grid Gallery

// Simple 3-column grid
[visual_portfolio 
  layout="grid"
  grid_columns="3"
  items_gap="20"
]

​
Square Grid with 4 Columns

[visual_portfolio 
  layout="grid"
  grid_columns="4"
  grid_images_aspect_ratio="1:1"
  items_gap="15"
]

​
Wide Format Grid

[visual_portfolio 
  layout="grid"
  grid_columns="2"
  grid_images_aspect_ratio="21:9"
  items_gap="30"
]

​
Gutenberg Block Configuration

In the Block Editor:
  1. Add a Visual Portfolio block
  2. Choose Grid layout
  3. Set number of columns (1-6)
  4. Configure aspect ratio if desired
  5. Adjust gap and styling options

​
Best Practices

  • You need consistent, uniform appearance
  • Images have similar dimensions
  • You want a clean, organized look
  • Content should align in perfect rows
  • Displaying products or team members
  • Use aspect ratio for maximum consistency
  • 3-4 columns work best for most screen sizes
  • Keep gaps between 10-30px for best readability
  • Test responsive behavior on actual devices
  • Enable lazy loading for image-heavy grids
  • Optimize images to consistent dimensions
  • Use pagination for galleries with 50+ items
  • Consider CDN for faster image delivery

​
Grid vs Masonry

Use Grid when...

  • Uniformity is important
  • Items have similar content
  • Clean alignment is priority
  • Showcasing products/services

Use Masonry when...

  • Items have varying heights
  • Dynamic layout is desired
  • Content varies significantly
  • Creating portfolio galleries

​
Common Issues

Items not aligning: Ensure all images have loaded before Isotope initializes. The plugin handles this automatically, but custom CSS can interfere.
Gaps between rows: If you see unexpected gaps, check that your aspect ratio settings are correctly applied to all items.
FireFox rendering issues: Visual Portfolio’s custom vpRows layout mode specifically addresses FireFox issues. If you still see problems, check for theme CSS conflicts.

​
Combining with Features

Grid layout works perfectly with:

​
Advanced Customization

For developers who want to customize the Grid layout: 
// Hook into Grid layout initialization
$(document).on('initLayout.vpf', (event, self) => {
  if (self.options.layout !== 'grid') return;
  
  // Custom styling
  self.addStyle('.vp-portfolio__item-wrap', {
    // Your custom styles
  });
});
See Custom Layouts for more information.

​
Related Layouts

Masonry Layout

For dynamic, Pinterest-style layouts

Tiles Layout

Create custom tile patterns

​
Source Code Reference

  • JavaScript: assets/js/layout-grid.js:1
  • Custom Layout Mode: assets/js/layout-grid.js:14
  • Isotope Library: assets/vendor/isotope-layout/dist/isotope.pkgd.min.js

Build docs developers (and LLMs) love

Get started for freeTalk to us