How to Use

Authorization

How to connect the plugin using your own Google credentials and test the new photo-picker flow. No app verification or Google approval is required.

Notice: Google retired the old Photos Library API on 31 March 2025, so the plugin can no longer auto-list your albums. It now uses Google’s Photos Picker API: you pick photos in Google’s own window, the plugin imports the selected images into your WordPress Media Library, and the gallery renders those local copies. Existing galleries created with the old version will appear empty until you re-pick their photos.

You use your own Google Cloud OAuth app, and only you (the site admin) ever sign in  and only to pick photos. Because the images are copied to your Media Library, the token is used only while importing, never when visitors view the gallery. So the app can stay unverified / in Testing forever; you simply click past the “unverified app” screen for your own app.

Step 1: Create a Google Cloud project & enable the Picker API

Go to the Google Cloud Console and create a new project (or pick an existing one).

Create a project here named [Your Project Name].

You will see three lines in the upper left corner; click there.

Hover over the APIs & Services menu, then click on Enable APIs & Services.

 Click the Enable APIs and Services button.

Search for Google Photos Picker and click on the Google Photos Picker API.

Enable the Picker API not the Library API The old “Google Photos Library API” is deprecated. You only need photospicker.googleapis.com.

Step 2: Configure the OAuth consent screen

Open APIs & Services click OAuth consent screen.

Choose User type: External and fill in the app name, your support email, and developer email.

Click on the Data Access menu, then on the Scopes step, click Add or remove scopes and add this scope (paste it in the manual field if it isn’t listed). Then click Save button:

https://www.googleapis.com/auth/photospicker.mediaitems.readonly

On the Test users step, add the Google account whose photos you’ll use.First, click the Audience menu. Next, find the Test users section and click the Add users button.

Set the Publishing status to In Production (recommended) or leave it as Testing either one works. You still do not need to submit for verification.

In Production is recommended Setting the app to In Production is the better choice because Google refresh tokens no longer expire after ~7 days you won’t have to regenerate the token to pick new photos. Even without verification, you simply click past the “unverified app” screen for your own app.

Testing mode note If you keep the app in Testing mode, Google refresh tokens expire after about 7 days. That only matters when you want to pick new photos  your already imported galleries keep working because the images live in your Media Library. When a token expires, just repeat Step 3.

Step 3: Create OAuth credentials & a refresh token

Create the OAuth client.

Open APIs & Services and click Credentials.

At the top of the page, click + Create Credentials and select OAuth client ID.

Application type: Web application.

Under Authorized redirect URIs, add: https://developers.google.com/oauthplayground/

Click Create and copy your Client ID and Client Secret.

Generate a refresh token (OAuth Playground)

Open the OAuth 2.0 Playground. Click the gear icon (top-right)  tick Use your own OAuth credentials, paste your Client ID and Client Secret.

In the left “Input your own scopes” box, enter the picker scope and click Authorize APIs:
https://www.googleapis.com/auth/photospicker.mediaitems.readonly

1. Sign in with your test-user Google account. When you see “Google hasn’t verified this app”, click Advanced → Go to … (unsafe) and allow access. (This is your own app — it’s safe.)
2. Back in the Playground, click Exchange authorization code for tokens.
3. Copy the Refresh token value.

Keep these private Your Client Secret and Refresh token are credentials. Only paste them into the plugin’s settings on your own site; never expose them publicly.

Step 4: Connect the plugin

1. In wp-admin, edit any post/page and add the Embed Google Photos block.
2. Open the block editor’s options menu (⋮)  Google Photos Block sidebar (or the “Open authorization” button on the block).
3. In the Authorization panel, paste your Client ID, Client Secret, and Refresh Token.
4. Click Save Information.

Connected The plugin exchanges your refresh token for an access token server-side and stores it. The block’s “Connect” prompt is replaced by the photo picker.

Step 5: Pick photos & publish

1. On the block, click Select from Google Photos.
2. A Google Photos window opens select the photos you want and confirm.
3. The plugin polls the session, then imports each picked image into your Media Library and shows the thumbnails in the editor.
4. Publish the page. Visitors see the local images in a responsive grid with a lightbox  no Google sign-in, no token, nothing that expires.

Display the Embed Google Photos

From the Block Library

In the Gutenberg editor, click the “+” icon in the top-left corner.

Then find the Embed Google Photos block and add it to your page. The block will appear in your editor right away.

From the Inline Listbox

In the Gutenberg editor, type ‘/’ and start typing the-embed-google-photos. A popup will appear with a list of blocks. Choose your block from that list.

From the Quick Listbox

Click the plus icon inside the content area. A popup will appear with a search bar and block options. Search for your block and add it.

Settings & Style

Step 1: Add the Gallery Block

1. Open the WordPress Block Editor on any post or page.
2. Click the + icon to add a new block.
3. Search for “Embed Google Photos”.
4. Click the block to add it to your page.

The block appears with a “Connect your Google Photos account” card, since no account is linked yet.

Step 2: Connect Your Google Account

The plugin uses your own Google API credentials so your photos and login details never pass through bPlugins’ servers.

1. In the block, click Open authorization.
2. In the sidebar that opens, click “Need help?” to follow Google’s steps for creating a Client ID, Client Secret, and Refresh Token in the Google Cloud Console.
3. Paste your Client ID into the first field.
4. Paste your Client Secret into the second field.
5. Paste your Refresh Token into the third field.
6. Click Save Information.

Once saved, you’ll see a “Connected!” confirmation, and the button changes to Update Credentials for next time.

Tip: These fields are write-only once saved, they display as •••••• (saved) and are never shown back to you or sent anywhere except Google. This is a security feature, not a bug.

Note: If your Google Cloud OAuth app is still in “Testing” mode, Google will expire your Refresh Token every 7 days. To avoid reconnecting weekly, go to Google Cloud Console → APIs & Services → OAuth consent screen and switch Publishing status to “In Production” (no verification required for this use case).

Step 3: Select Your Photos

1. Back in the block, click Select from Google Photos.
2. A Google picker window opens in a popup.
3. Choose the photos and/or videos you want to display.
4. Confirm your selection in the popup.

The plugin downloads your selected media into your own WordPress Media Library and displays them in the block automatically.

Tip: Already have a gallery and want to add more? Click Add More Photos instead of starting over.

Success indicator: You should now see your photos appear in a grid inside the block editor, like this: [Screenshot: Populated gallery grid in the editor]

Import & Connection

How to bring your photos and videos into WordPress either by hand-picking them, or by keeping a gallery synced automatically from a shared album.

Select photos from Google Photos

1. On the block, click Select from Google Photos.
2. Google’s picker opens in a popup window.
3. Choose the photos and/or videos you want.
4. Confirm your selection.

The plugin downloads everything you picked straight into your WordPress Media Library.

Where your imported media is stored

Every imported photo and video becomes a normal WordPress attachment in Media → Library, just like anything you’d upload by hand:

1. They show up in your regular Media Library.
2. You can reuse them anywhere else in WordPress.
3. They count toward your hosting’s normal storage see Media Cleanup Manager if you need to check usage or remove old imports.

Filter by media type

If your gallery has both photos and videos, you can limit what shows in the editor by opening the General tab, navigating to the Media Type panel, and choosing All Media, Photos, or Videos from the dropdown menu.

This filters what the editor displays and works with. See Frontend media filter bar if you want visitors to filter this on the live page themselves.

Automatic import with Album Auto-Sync

Keep your gallery automatically up to date using a shared Google Photos album, eliminating the need for manual re-importing. This works with any public shared link and does not require connecting your Google account.

Go to the General tab’s Album Auto-Sync panel, paste your link, and click Sync Now. To keep it updated continuously, enable Auto-sync in background and set an interval (15 minutes, Hourly, or Daily).

Success indicator: All current photos from the shared album appear in the gallery right after syncing, and new photos added later appear automatically on your chosen schedule.

Live Event / Wedding Mode

Perfect for live events, this feature automatically displays new guest photos without a page reload, highlighted by a pulsing “Live” badge.

Enable Live Event Mode in the Album Auto-Sync panel and set a quick refresh interval (30s to 5m). Use this rapid browser-side polling only during active events.

Tip: Guests drop their photos into the shared Google Photos album from their own phones no login to your site needed and the gallery wall updates itself as new photos arrive.

Multiple albums in one gallery

 Combine multiple shared albums into a single gallery with optional tab navigation.

In the Album Auto-Sync panel, add your links and labels under Multiple Albums, click Sync all albums now, and enable Show album tabs on frontend.

 Sync Settings:

1. Check Every: Background server sync to import new photos into your library.
2. Refresh Every: Rapid browser-side poll (Live Event Mode) to display new photos to active visitors without reloading.

Layouts

Choose a layout

Go to the General tab, navigate to the Layout panel, and choose one of the options from the Layout dropdown: Grid, Masonry, Carousel, Memories, Justified / Mosaic, or Timeline.

Grid Layout

Grid Columns control how many columns appear. Column and Row Gap set the spacing between items.

Masonry

For a Pinterest-style layout where each photo keeps its own natural aspect ratio instead of being cropped to match its neighbors, set the Layout to Masonry and adjust the columns and gaps as described below.

Tip: Because Masonry preserves each photo’s real proportions, the Image Aspect Ratio panel is hidden for this layout  there’s nothing to crop.

Carousel / Slider

Choose the Carousel layout, where you can set the slides per view and column gap.

Carousel Settings

1. Autoplay Speed: Determines how quickly the slides transition automatically.
2. Continuous Slide Looping: Ensures the gallery seamlessly restarts from the beginning after reaching the last slide.
3. Clickable Arrows: Adds left and right arrows, allowing visitors to manually skip to the next or previous slide.
4. Pagination Dots: Displays clickable dots below the gallery to show the total number of slides and the current position.

Advanced Options:

5. Transition Effects: Customizes the visual animation style when moving from one slide to another.
6. Scroll Speeds: Controls the duration of the sliding animation itself.
7. Centered Slides: Keeps the active slide perfectly centered on the screen instead of aligning it to the left edge.
8. Grab Cursor: Changes the mouse pointer to a hand icon, visually indicating that the slider can be dragged.
9. Pause on Hover: Temporarily stops the autoplay when a cursor hovers over the gallery, allowing visitors to look at a photo longer.
10. Free Scrolling: Allows visitors to swipe or scroll smoothly without the gallery snapping rigidly to the next frame.

Memories / Stories

To display Google Photos style round story bubbles that open into a full slideshow when clicked, set the Layout to Memories. 

The behavior of the opened slideshow is managed by the same Carousel Settings panel, where you can configure Autoplay, Loop, Arrows, and Dots.

Note: Captions don’t support the “below image” position in this layout, since bubbles are circular only overlay captions are available.

Justified / Mosaic

To achieve a classic photographer portfolio look where rows of photos fill edge-to-edge with varying widths, set the Layout to Justified / Mosaic and adjust the Columns, Column Gap, and Row Gap as you would with any other layout.

Timeline

For travel blogs and event recaps, set your Layout to Timeline to group photos under pinned date headers as visitors scroll.

Open the Timeline Settings panel to group photos by Day, Month, or Year, sort them by newest or oldest, and keep the active date pinned with Sticky Date Headers.

Responsive columns

To ensure your gallery looks perfect on every screen, set a distinct column count for each device size. Open the Layout panel, use the device switcher (desktop, tablet, or mobile) above the Columns slider to select a device, and adjust the count. Repeat this process for the remaining devices.

Within the same panel, you can control the spacing between your media using px, %, or em units. Set the Column Gap for horizontal spacing and the Row Gap for vertical spacing (note that Row Gap is hidden in Carousel layouts).

Image aspect ratio

To force every photo to the same crop ratio in Grid, Justified, Mosaic, or Timeline layouts, open the Image Aspect Ratio panel and choose from 16:9, 4:3, 1:1, 3:4, or 9:16.

(Note: This panel is automatically hidden for the Masonry layout, which preserves each photo’s natural dimensions).

Tip: Need one photo cropped differently than the rest? See Focal point crop for per-image fine-tuning.

Image Style

Go to the Style tab’s Image panel to fully customize your photos by adjusting their border settings, applying advanced independent corner radii, and adding box shadows for depth. Additionally, you can enable and configure a Gradient Overlay to apply a permanent color tint across all your images.

Tip: A dark-to-transparent gradient from the bottom is a common choice when you also show captions as an overlay  it keeps caption text readable against busy photos.

Frontend media filter bar

Allow visitors to filter mixed photo-and-video galleries directly on the page. Simply go to the General tab’s Frontend Filter panel to enable the Show Filter Bar, where you can also optionally customize the text for your “All,” “Photos,” and “Videos” buttons.

Success indicator: Visitors see All / Photos / Videos buttons above the gallery, and clicking one filters the visible items instantly.

Design Presets

Quickly apply a complete design or save your own for later.

Navigate to the Design Presets panel within the Style tab and click any preset card to apply it instantly.

The applied preset shows an Active badge. If you tweak any setting afterward, the badge changes to Modified. Click Reset to preset to discard your tweaks and snap back to the original.

Your saved presets appear under Your Presets and can be applied to any future gallery. Click the × next to a custom preset to delete it.

Captions & Hover Effects

Learn how to display captions and add hover effects to your photos.

To show captions, go to the General tab’s Caption panel and enable Show Caption.

With captions enabled, use the Caption panel’s Source dropdown to display the photo’s Title or Date, and the Position dropdown to place it permanently Below Image or as an Overlay on hover.

Note: This option is hidden for the Memories layout, which only supports overlay-style captions.

Style Caption Typography And Color

Customize your text in the Style tab’s Caption panel (visible once captions are enabled) by adjusting the Typography (font, size, weight) and Color.

Add a hover effect

Go to the Style tab’s Image panel and select a Hover Effect (Zoom, Overlay, or Caption Slide-in). Additional controls will appear based on your choice, allowing you to easily customize the Zoom Amount, Overlay Color, and overall Animation Speed.

Tip: “Caption Slide-in” pairs well with the “Overlay” caption position above the caption slides up from the bottom on hover instead of just appearing.

Adding Hover Icons and Meta Overlays

In the Style tab’s Image panel, you can enable Show Hover Icon, activate a Gradient Overlay (hover) if your hover effect is set to overlay, and turn on Meta Overlay on Hover.

Search & Filtering

Turn on the search bar

Enable the search bar in the General tab and choose either a Classic or Expandable style to let visitors filter photos live. Under Search Features, activate Voice Search to allow users to search by speaking. 

Finally, turn on Autocomplete and Highlight Matches to display dropdown suggestions and automatically bold the matching text as visitors type.

Tip: Hover over any Search Feature toggle in the editor to see a short explanation of what it does.

Fuzzy search and related shortcuts

Enable Advanced Search in the Search Bar panel to instantly activate multiple features with a single toggle:

1. Fuzzy Search: Typo-tolerant matching (e.g., “beech” finds “beach”).
2. Keyboard Shortcut: Press “/” anywhere to focus the search box.
3. Recent Searches: Saves past searches locally in the user’s browser.
4. “Did you mean…“: Suggests spelling corrections when no results are found.
5. Sticky Search Bar: The search box stays visible as you scroll down the gallery.

Customize your search bar’s appearance by setting the Alignment (left/center/right), adjusting the Search Bar Width (in px, %, or em), and selecting a custom Search Icon.

Style the search bar

Go to the Style tab’s Search Bar panel to easily customize the typography, colors, dimensions, and borders.

Photo Filters & Cropping

Apply a visual filter preset that reveals the original photo on hover.

In the Style tab’s Image panel, select a global Photo Filter to instantly apply it to your entire gallery. Once a filter is applied, enable Reveal original on hover below the dropdown to show the unfiltered image when a visitor hovers over it.

Focal point crop

Fine-tune an individual photo or set a single focal point for all your photos.

In the General tab’s Focal Point (Crop) panel, drag the crosshair to set a default focal point, or enable Fine-tune per image to manually adjust the crop for specific photos.

Tip: Use the global focal point for a gallery-wide default, then fine-tune only the handful of photos where a face or subject would otherwise get cropped out.

Ken Burns motion

In the Style tab’s Image panel, enable Ken Burns Motion and adjust the speed (lower is faster), or simply click Reset to default to return to 12 seconds.

Lightbox

Lightbox settings

Default Behavior

The lightbox automatically opens when a photo or video is clicked, and keyboard navigation (arrow keys to browse, Esc to close) works immediately without any setup.

Configuration Options

Note: All of these settings are found by selecting your block and going to the Settings sidebar → General tab → Lightbox panel.

1. Show Captions: Enable Show Caption to display text with your media (on by default).
2. Thumbnails Bar: Enable Thumbnails Bar to show a clickable strip of images at the bottom (on by default).
3. Download Button: Enable Download Button so visitors can save the original, full-resolution file.
4. Social Share Buttons: Enable Social Share Buttons to display options for Facebook, X, Pinterest, and a “Copy-link” button.
5. Deep-Link to a Photo: Enable Deep-link to Photo to update the page URL (e.g., ?photo=N) as visitors browse..
6. Slideshow Autoplay: Enable Slideshow Autoplay and set your preferred Slideshow Speed (in milliseconds).
7. Lightbox Skin: Select a visual theme from the Skin dropdown

You will see a popup with the options you enabled in your settings. Look at the image below for an example:

EXIF display

In the Lightbox panel, enable Show EXIF (camera info) to display the camera details for your photos..

Note: This only shows data for photos that actually contain EXIF metadata.

Per-image custom link

Make a specific photo link out to an external URL when clicked, instead of opening the lightbox.

In the General tab’s Per-Image Links panel, enter a destination URL for any photo and optionally choose to open the link in a new tab.

Note: A photo with a custom link set no longer opens the lightbox when clicked.

Video playback options

For galleries that include videos, open the General tab → Video panel.

1.  Show Controls – display play/pause/volume controls.
2. Autoplay – start the video automatically when opened (muted automatically, since browsers require it).
3. Muted – mute video audio by default.
4. Loop – restart the video when it ends.
5. Fit To Window Height – size the player to the browser window’s height.
6. Autoplay in Grid – play videos muted and looping directly inside the gallery thumbnails, as a live preview, without opening the lightbox.

Pagination

Go to the General tab’s Pagination panel to control how your photos load:

1. Choose a Type: Set your pagination style to Show All, Load More, or Pagination (numbered links).
2. Set Items Per Page: Use the slider to choose how many photos display at once (available for Load More or Pagination).
3. Customize Button Text: Enter a custom label if you are using the Load More option.

Style the button

Go to the Style tab’s pagination/Load More panel to customize the typography, button colors, padding, and borders.

Performance & SEO

How the plugin keeps your gallery fast and search-engine friendly.

Automatic lazy-load

Off-screen photos load a blurred, low-resolution placeholder first, then swap in the full image only as a visitor scrolls near it. Nothing to set up always on.

Automatic responsive images (srcset)

The plugin serves the right-sized image for each visitor’s screen using WordPress’s own responsive image sizes. Nothing to set up automatic.

Automatic Schema.org markup

Each gallery outputs Schema.org ImageObject structured data (JSON-LD) so Google can better understand and index your images. Nothing to set up generated automatically; it doesn’t send any data to schema.org itself.

Per-image alt text

In the General tab’s Image Alt Text (SEO) panel, type a short description for each photo, or leave the field blank to automatically fall back to the photo’s title.

Tip: Describe what’s in the photo (e.g. “Bride and groom cutting the cake”), not just its filename.

Automatic WebP conversion

Automatically shrink imported images for faster loading.

In the General tab’s Import panel, enable Convert to WebP on import to automatically convert new photos as they are added, or click Convert N image(s) to WebP to retroactively convert any previously imported photos.

Usability

Go to the General tab’s Reorder Photos panel and simply drag any thumbnail to a new position in the list.

Frontend sort dropdown

You can easily add convenient features for your visitors by going to the General tab’s Gallery Extras panel:

1. Sort Dropdown: Allow visitors to reorder the gallery by Newest, Oldest, or Random without affecting your default order.
2. Photo Count Badge: Display the total number of images (e.g., “125 photos”) right above the gallery.
3. Preview Limit: Show only a set number of photos initially, followed by a “View all” button. Set this to 0 to display everything.
4. Download zip: Enable Download All (ZIP) to let visitors download the entire gallery at once, and optionally customize the button text.

Import / Export gallery settings

To reuse a gallery’s layout and styling, go to the Style tab’s Import/Export panel to Copy or Download the settings as a JSON file, then Paste or Upload it to your new gallery.

Client Delivery & Protection

Built for photographers and anyone sharing private galleries: let clients pick favorites, control downloads, and restrict access.

Client Picks (Proofing)

Let clients heart/select their favorite photos and submit their picks straight to you.

To set up client proofing, select your block and navigate to the Settings sidebar -> General tab -> Client Proofing panel. Turn on Enable Proofing and configure the following:

1. Send Selections To: Enter the email address that should receive the client’s submissions.
2. Selection Title: Add a name or title for the proofing session.
3. Optional Extras: You can also enable Allow Per-Photo Comments, customize your Submit Button Text, or turn on Auto-hide Success Message (and set the delay in seconds).

Once you are finished, simply publish the gallery and share the link with your client!

On the image proofing frontend, users can leave comments that you can easily view from the admin dashboard.

Every submission is emailed to the address you set, and saved in your WordPress admin under Google Photos → Client Picks.

Tip: Pair this with Password protection so only your client can access the gallery.

Gallery Protection

Go to the Style tab’s Protection panel to configure your gallery’s security and visibility settings:

1. Expire Gallery: Automatically hide the gallery after a specific time (ideal for time-limited clients). Enable this feature, set your required Hide After date, and optionally add a Show From date or a custom Expiry Message.
2. Gallery Password: Simply type a password into this field to require visitors to enter it before they can view the gallery.
3. Disable Right-Click & Download: Enable this to discourage casual downloading by turning off the right-click menu and image dragging.

Note: The date fields use your WordPress site’s timezone, shown alongside the field. Note: This deters casual downloading only  it isn’t a strict security measure.

Automatic watermark

Apply your logo as a watermark to every photo automatically during import.

1. Select the block → Settings sidebar → General tab → Watermark panel.
2. Enable Enable Watermark.
3. Click Select Logo and choose your logo image (Change Logo / Remove to update later).
4. Choose a Position from the 3×3 grid.
5. Fine-tune Offset X (px) and Offset Y (px).
6. Set Size (% of image width) and Opacity (%).

Note: The watermark is applied server-side during import  it becomes part of the saved image file. Photos already imported before turning this on won’t be retroactively watermarked.

Use the shortcode outside Gutenberg

Every gallery also works in the Classic Editor, page builders, widget areas, and theme template files.

Open the gallery in the block editor, copy the displayed shortcode (e.g., [google_photos id=”123″]), and paste it anywhere WordPress supports shortcodes.

Paste the shortcode on this page, then view the frontend to see the results.

Showing wedding memories via shortcode

Analytics & Maintenance

Track how visitors use your galleries, and keep your Media Library tidy as galleries change over time.

Gallery Analytics

Analytics must be turned on per gallery.

In the General tab’s Gallery Extras panel, enable Track Analytics, then publish or update your page to save the changes.

View your analytics dashboard

To view your gallery performance, go to Google Photos → Analytics in your WordPress admin sidebar to check your overall stat cards (like total views and lightbox opens), then scroll down to see a detailed, per-gallery breakdown with a visual bar chart.

Tip: Only galleries with Track Analytics enabled contribute data here.

Check storage with Media Cleanup Manager

Go to Google Photos → Media Cleanup in your WordPress dashboard to review your storage statistics and permanently delete unused, “orphaned” photos from your Media Library.

Note: This permanently deletes the files it cannot be undone. Double-check the orphan count first.