Description
Matcha Gallery is a free, lightweight image gallery and photo gallery plugin for WordPress with 7 responsive layouts: Grid, Masonry, Mosaic, Bento, Justified, Lookbook, and Cinema Reel.
Create beautiful masonry galleries, portfolio galleries, and photo walls in seconds with the built-in Matcha Studio visual editor. Includes AI-powered auto-tagging (Google Gemini & OpenAI), realistic picture framing, client proofing, color palette filtering, and a native Gutenberg block.
Built for photographers, visual artists, designers, and eCommerce portfolios. Zero jQuery dependencies, under 15KB frontend runtime, and 100/100 PageSpeed scores.
Live Demo & Documentation | Support & Help
Key Highlights
- Matcha Studio Visual Editor: A distraction-free, 3-panel visual workspace inspired by Figma. Customize layouts, picture framing, drop shadows, and matting with real-time WYSIWYG preview.
- Interactive 3D Spatial Depth Tilt (Pro): Hardware-accelerated cursor perspective tilt with realistic specular glare reflections and dynamic card elevation.
- Atmospheric Aura Dual-Layer Bloom (Pro): Rich ambient lighting halo with focal-point bloom synchronized with image color palettes.
- AI Vision & Metadata Generator: Powered by Google Gemini AI. Automatically generates ADA-compliant alt text, human-readable titles, descriptive captions, and SEO keyword taxonomy.
- 7 Algorithmic Layout Blueprints:
- Classic Grid — Uniform aspect ratio with responsive column presets.
- Pinterest Masonry — Fluid cascading heights preserving native aspect ratios.
- PhotoBlocks Mosaic — Custom geometric tile spans (1×1, 2×1 wide, 1×2 tall, 2×2 hero).
- Bento Showcase — Modern tech-style hero spread.
- Justified Rows — Flickr-style edge-to-edge justified rows.
- Lookbook Duet — 2026 editorial magazine layout with staggered cadence.
- Cinema Reel — 16:9 widescreen horizontal runway with smooth momentum scroll-snap.
- 1-Click ✨ Smart Fill: AI analyzes image aspect ratios across your entire collection and automatically assigns the optimal geometric tile layout with one click.
- In-Frame Pan & Zoom Cropping: Interactive 2D target reticle and zoom slider (1.0x to 2.5x) to set pixel-perfect focal framing without cutting off heads or subjects.
- Realistic Picture Framing & Matting: 5 gallery-grade picture frames (White Matting, Slim Black Metal, Natural Oak Wood, Brushed Gold Brass, Glass Float) with customizable 0–32px matting margins.
- Multi-Section Gallery Chapters: Organize a single gallery into tabbed chapters (e.g. Ceremony, Reception, Portraits or Living Room, Bedroom, Kitchen) with smooth animated switching.
- AI Color Swatches & Live Filter Toolbar: Instant color dot filter buttons extracted by AI, plus live keyword search and animated category filter pills.
- Client Proofing & Shoppable Portfolios: Visitors can favorite photos with heart icons (
🤍 → ❤️) and export clean selection lists, or click glassmorphic Buy / Shop Now buttons. - 1-Click 📷 Export Wall & Client Proofing Sheet: Download a 2x crystal-clear PNG snapshot of your arranged gallery wall, or print a branded client proposal sheet with dimensions and pricing.
- WordPress 7.0 Connectors Ready: Seamlessly bridges with the native WordPress 7.0+ AI Connectors API (
Settings > Connectors) and environment credentials (wp-config.php). If active on your site, Matcha auto-connects with zero duplicate setup. - Gutenberg Block & Shortcode: Embed galleries seamlessly via the native
[matcha_gallery id="..."]shortcode or the dedicated Gutenberg block.
Third-Party Services
This plugin can optionally integrate with the following external third-party AI provider services to generate image alt-text, titles, captions, keyword tags, color swatches, and focal cropping coordinates. All AI features are entirely optional and require you to provide your own API key in the plugin settings.
-
Google Gemini AI API (Google LLC)
- What it is used for: Analyzes uploaded image attachments to generate descriptive alt-text, titles, captions, keyword tags, dominant color palettes, and focal point coordinates.
- What data is sent and when: Image URLs or base64 image data are sent over secure HTTPS only when you explicitly click « ⚡ AI Enhance », click « Generate AI Metadata » in the WordPress Media Library, or enable the « Auto-generate on upload » option in settings.
- Privacy Policy: https://policies.google.com/privacy
- Terms of Service: https://ai.google.dev/terms
-
OpenAI API (OpenAI, Inc.)
- What it is used for: Vision-based image metadata generation, keyword tagging, and alt text analysis for users configuring an OpenAI API key.
- What data is sent and when: Image data and text prompts are sent over secure HTTPS only when triggered by user request in the editor or media library.
- Privacy Policy: https://openai.com/policies/privacy-policy/
- Terms of Service: https://openai.com/policies/terms-of-use/
-
OpenRouter API (OpenRouter)
- What it is used for: Multi-model AI routing allowing users to connect alternative vision models using an OpenRouter API key.
- What data is sent and when: Image data and prompt requests are sent over secure HTTPS only when triggered by user request.
- Privacy Policy: https://openrouter.ai/privacy
- Terms of Service: https://openrouter.ai/terms
Captures d’écrans

Blocs
Cette extension fournit 1 bloc.
- Matcha Gallery Image gallery & photo gallery block with masonry, grid, mosaic layouts, lightbox, and AI auto-tagging.
Installation
- Upload the
matcha-galleryfolder to your/wp-content/plugins/directory, or install directly through Plugins Add New in your WordPress dashboard. - Activate the plugin through the Plugins menu in WordPress.
- Navigate to Matcha AI AI Settings and enter your free Google Gemini API key (or OpenAI key).
- Go to Matcha AI All Galleries and click Add New Gallery to open the Matcha Studio visual editor.
- Add photos, customize your layout and framing, and copy your shortcode
[matcha_gallery id="..."]into any page or post.
FAQ
-
Do I need a paid API key to use the AI features?
-
No! Google Gemini offers a generous free tier (up to 15 requests per minute) that is completely free of charge. You can generate a free API key at Google AI Studio.
-
Can I use Matcha Gallery without AI?
-
Yes, absolutely! All 6 layouts, picture framing, matting, multi-section chapters, lightboxes, and shortcodes work 100% out of the box without configuring an API key.
-
Will AI overwrite my existing image alt text?
-
By default, no. Matcha Gallery only enriches images with missing alt text or captions. You can toggle « Overwrite existing metadata » in Settings if you wish to re-generate everything.
-
Does Matcha Gallery work with WordPress 7.0 AI Connectors?
-
Yes! Matcha Gallery includes a Smart Hybrid bridge. If your site is running WordPress 7.0+ with an active AI connector configured in Settings > Connectors (or via wp-config.php), Matcha auto-detects it. You can also provide a direct API key (such as a 100% free Google Gemini Flash key) anytime.
-
Is Matcha Gallery fast and lightweight?
-
Yes! The frontend runtime is under 15KB of vanilla JavaScript with zero jQuery or external framework dependencies. It uses native CSS Grid and Flexbox for maximum rendering speed and 100/100 Google PageSpeed scores.
-
How do I embed a gallery into a page?
-
You can insert the native Matcha Gallery Gutenberg block, or paste the shortcode
[matcha_gallery id="123"]into any block, page builder (Elementor, Divi, Beaver Builder), or widget area. -
Does this image gallery work with Elementor?
-
Yes! Matcha Gallery includes a native Elementor widget. Simply search for « Matcha Gallery » in the Elementor widget panel, drag it onto your page, and select your gallery. No shortcodes needed.
-
Can I create a masonry gallery without coding?
-
Absolutely! Select the Masonry layout blueprint in the visual Studio editor and your photos will automatically cascade in a Pinterest-style masonry grid preserving each image’s native aspect ratio. No code, no configuration — just pick Masonry and publish.
-
Is this a good photo gallery plugin for photographers?
-
Yes, Matcha Gallery was designed specifically for photographers. Features include client proofing with heart favorites, multi-section gallery chapters (Ceremony, Reception, Portraits), realistic picture framing with gallery-grade moldings, AI-powered SEO alt text, and a visual Studio workspace inspired by professional editing tools.
-
What makes Matcha Gallery different from other gallery plugins?
-
Matcha Gallery is the only free WordPress gallery plugin that combines AI-powered image tagging, 7 layout blueprints (including Masonry, Mosaic, Bento, and Cinema Reel), realistic picture framing with 5 frame styles, and a Figma-inspired visual editor — all in under 15KB with zero jQuery dependencies.
-
Can I use this as a portfolio gallery for my website?
-
Yes! Matcha Gallery works perfectly as a portfolio gallery. Use the Grid or Lookbook Duet layout for clean, professional portfolio presentations. Add category keywords for filterable portfolio sections, and use the lightbox for full-screen viewing.
Avis
Contributeurs/contributrices & développeurs/développeuses
« Matcha Gallery – Image Gallery, Photo Gallery & Masonry for WordPress » est un logiciel libre. Les personnes suivantes ont contribué à cette extension.
ContributeursLe développement vous intéresse ?
Parcourir le code, consulter le SVN dépôt, ou s’inscrire au journal de développement par RSS.
Journal des modifications
1.0.5
- Fix: Resolve undefined variable $has_sections in Smart_Gallery_Block on sites with WP_DEBUG enabled.
- Hardening: Add default fallbacks for chapter section attributes during block and shortcode rendering.
- Compatibility: Broadened minimum PHP requirement from 8.0 down to PHP 7.4.
1.0.4
- Feature: 1-Click Demo Gallery Generator — instant 6-photo pre-configured Masonry/Bento demo gallery creator with sample photography pack and welcome onboarding guide.
- Feature: WooCommerce Quick-Cart Drawer — seamless 1-click AJAX Add to Cart slide-out drawer directly from gallery photo hover dock and lightbox view.
- Feature: Client Proofing Badges & Dispatch — client favorites submission counter badge in Galleries Manager table and photographer notification support.
- Enhancement: WordPress 7.1.4 compatibility verified across all layout engines, REST endpoints, and block rendering.
- Enhancement: SEO & directory search optimization — targeted keyword indexing for image gallery, photo gallery, masonry gallery, and Elementor integration.
- UX: Zero-AI Required reassurance banner added to Settings, clarifying full standalone operation without third-party API keys.
1.0.3
- UI: Figma-inspired Matcha Studio workspace refresh — clean separated panels, high-contrast controls, and fluid responsive canvas preview.
- Fix: High-specificity chapter tab CSS resets to prevent theme styling bleeds on frontend galleries.
- Fix: Hardened REST API permissions with granular per-post and per-attachment authorization callbacks.
- Pro: Full support for Interactive 3D Spatial Depth Tilt and Atmospheric Aura dual-layer lighting bloom with Matcha Gallery Pro.
- Maintenance: Upgraded SortableJS to stable 1.15.7 and optimized frontend script bundles.
1.0.2
- Feature: Smart Hybrid WordPress 7.0+ AI Connectors Bridge (
Settings > Connectors) — auto-detects site-level OpenAI and Google Gemini credentials with fallback to free direct keys. - Feature: Lookbook Duet layout blueprint — editorial 2-column spread with alternating cadence and caption margins.
- Feature: True Continuous CSS Multi-Column Masonry — seamless vertical column masonry with fluid responsive breakpoints.
- Feature: Cold-load thumbnail preloading and instant frame aspect-ratio reservation for zero layout shifts (CLS < 0.01).
- Feature: Obsidian Studio UI refresh — refined high-contrast monochrome studio workspace with streamlined layout tabs and synchronized skins.
- Asset: High-CTR WordPress.org Pure Symbol Icon Suite (256×256, 128×128, and scalable SVG) optimized for plugin directory and wp-admin search visibility.
- Fix: Strict Pro feature isolation — ensure Spatial 3D tilt, holographic physics, client proofing, shoppable pricing dock, and advanced toolbar skins cleanly fall back to free standards when Pro is inactive.
- Enhancement: Translation catalogue synchronization and optimized production bundle packaging.
1.0.1
- Fix: Admin sidebar menu icon sizing on the WordPress dashboard constrained to 20x20px with inline SVG data URI and global head style guard.
- Feature: Curated Style Presets (Exhibition Hairline Frame, Architectural Curtain, Cinematic Pullback, Minimalist Drawer).
- Enhancement: Layout rendering performance and zero-CLS image frame reservation.
- Enhancement: Codebase hygiene, translation template updates, and package optimizations.
1.0.0
- Initial public release on WordPress.org.
- Matcha Studio 3-panel dark workspace editor.
- 6 Algorithmic layout blueprints: Grid, Masonry, Mosaic, Pinwheel, Bento, and Justified.
- 1-Click Smart Fill aspect-ratio matcher.
- Picture Framing & Matting system (5 realistic frame styles).
- In-Frame Pan & Zoom cropping with 2D focal reticle.
- Multi-Section Gallery Chapters (tabbed sub-stories in 1 gallery).
- 1-Click 2x High-Res PNG Wall Snapshot & PDF Client Proofing Sheet export.
- AI Vision metadata enrichment via Google Gemini (alt text, titles, captions, colors, focal points).
- Frontend live search, color swatch filter, proofing tray, and accessible lightbox.
- Native Gutenberg block and
[matcha_gallery]shortcode. - Local vendored JS dependencies (zero CDN reliance).
