PKB-theme Demo

Gallery Slider Documentation

1x
Ready

Click anywhere in the title or content to start reading from that position, or use the controls below to play the entire post.

PKB Theme
Created:
documentation , components
gallery , slider , images ...

The Gallery Slider component provides an elegant way to display multiple images with navigation controls, thumbnails, and captions. This guide covers everything from basic usage to advanced customization.

File Organization for Images

Understanding how to organize your images is crucial for effective gallery management:

Hugo Site Structure
├── static/
│   └── images/
│       ├── docs/
│       │   └── gallery-slider-doc/
│       │       ├── landscape-1.jpg
│       │       ├── landscape-2.jpg
│       │       ├── portrait-1.jpg
│       │       └── thumb-landscape-1.jpg  ← Optional thumbnails
│       ├── gallery/
│       │   ├── nature/
│       │   │   ├── forest-1.jpg
│       │   │   └── forest-2.jpg
│       │   └── architecture/
│       │       ├── building-1.jpg
│       │       └── building-2.jpg
│       └── posts/
│           └── my-post/
│               ├── hero.jpg
│               └── detail.jpg
├── content/
│   └── posts/
│       └── my-gallery-post.md  ← Your content file
└── layouts/
    └── partials/
        └── gallery-slider.html  ← Component template
aa.Organization Tips: Group images by topic or post in subdirectories. Use consistent naming conventions like image-name.jpg and optional thumb-image-name.jpg for custom thumbnails.

URL Structure

  • Local images: /images/docs/gallery-slider-doc/landscape-1.jpg
  • Web images: https://example.com/image.jpg
  • Relative paths: Always start with / for Hugo static files

Here’s a basic gallery with local images:

Code: We replaced {{ with {{ "{{" }} and }} with {{ "}}" }} so this code were visible; the actual segment starts with… {{ <, no space.

{{ "{{" }}< gallery-slider 
  id="basic-gallery"
  src1="/images/docs/gallery-slider-doc/helenium-8985687_1280.jpg"
  alt1="Beautiful landscape view"
  caption1="Mountain landscape at sunrise"
  src2="/images/docs/gallery-slider-doc/karsten-winegeart-AW76trwVU08-unsplash.jpg"
  alt2="Another landscape"
  caption2="Forest path in autumn"
  src3="/images/docs/gallery-slider-doc/nataliya-melnychuk-V5s-XShdujI-unsplash.jpg"
  alt3="Portrait orientation"
  caption3="Vertical composition example"
{{ "}}" }}

You can also use images from external sources:

Code:

{{ "{{" }}< gallery-slider 
  id="web-gallery"
  src1="https://picsum.photos/800/600?random=1"
  alt1="Random image 1"
  caption1="Beautiful random landscape"
  src2="https://picsum.photos/800/600?random=2"
  alt2="Random image 2"
  caption2="Another stunning view"
  src3="https://picsum.photos/600/800?random=3"
  alt3="Random image 3"
  caption3="Portrait orientation example"
{{ "}}" }}
bb.Performance Note: External images may load slower than local images. Consider downloading important images to your static folder for better performance and reliability.

For better performance and control, you can specify custom thumbnail images:

Code:

{{ "{{" }}< gallery-slider 
  id="thumbnail-gallery"
  showThumbnails="true"
  src1="/images/docs/gallery-slider-doc/street-food-9587641_1280.png"
  thumb1="/images/docs/gallery-slider-doc/helenium-8985687_1280.jpg"
  alt1="Landscape with custom thumb"
  caption1="Custom thumbnail example"
  src2="/images/docs/gallery-slider-doc/vadim-sadovski-rvkk2qqfE4M-unsplash.jpg"
  alt2="Auto-generated thumbnail"
  caption2="Auto-generated thumbnail (uses main image)"
{{ "}}" }}

Create a self-advancing slideshow:

Code:

{{ "{{" }}< gallery-slider 
  id="autoplay-gallery"
  autoplay="true"
  interval="3000"
  showThumbnails="false"
  src1="/images/docs/gallery-slider-doc/helenium-8985687_1280.jpg"
  alt1="Auto slide 1"
  caption1="Autoplay every 3 seconds"
  src2="/images/docs/gallery-slider-doc/pawel-czerwinski-mrCMyoadfBM-unsplash.jpg"
  alt2="Auto slide 2"
  caption2="Hover to pause autoplay"
  src3="/images/docs/gallery-slider-doc/nataliya-melnychuk-V5s-XShdujI-unsplash.jpg"
  alt3="Auto slide 3"
  caption3="Click navigation to restart timer"
{{ "}}" }}

For a cleaner look without thumbnail navigation:

Code:

{{ "{{" }}< gallery-slider 
  id="minimal-gallery"
  showThumbnails="false"
  src1="/images/docs/gallery-slider-doc/plums-8932336_1280.jpg"
  alt1="Minimal slide 1"
  caption1="Clean, minimal interface"
  src2="/images/docs/gallery-slider-doc/pawel-czerwinski-mrCMyoadfBM-unsplash.jpg"
  alt2="Minimal slide 2"
  caption2="Focus on the images"
  src3="/images/docs/gallery-slider-doc/vadim-sadovski-rvkk2qqfE4M-unsplash.jpg"
  alt3="Minimal slide 3"
  caption3="Navigation via arrows and dots only"
{{ "}}" }}

Main Parameters

ParameterTypeDefaultDescription
idstring“gallery”Unique identifier for the gallery
autoplaybooleanfalseEnable automatic slideshow
intervalnumber5000Autoplay interval in milliseconds
showThumbnailsbooleantrueDisplay thumbnail navigation

Image Object Properties

PropertyTypeRequiredDescription
srcstring✓Main image URL (local or external)
altstring✓Alternative text for accessibility
captionstring✗Text displayed below image
thumbstring✗Custom thumbnail URL (optional)
cc.Accessibility: Always provide meaningful alt text for screen readers. Captions are optional but enhance user experience by providing context.

Advanced Usage Examples

Mixed Content Gallery

CSS Customization Variables

The gallery slider uses CSS custom properties for easy theming:

Best Practices

Image Optimization

  • File size: Keep images under 500KB for web delivery
  • Dimensions: Use consistent aspect ratios when possible
  • Format: Use WebP or JPEG for photos, PNG for graphics with transparency
  • Thumbnails: Create 80x80px thumbnails for better performance

Accessibility

  • Always provide descriptive alt text
  • Use semantic HTML structure (maintained by the component)
  • Ensure keyboard navigation works (arrow keys supported)
  • Test with screen readers

Performance

  • Lazy load images not currently visible (built into component)
  • Use local images when possible for faster loading
  • Consider CDN for external images
  • Optimize thumbnail sizes

User Experience

  • Keep captions concise but informative
  • Use autoplay sparingly (can be distracting)
  • Provide multiple navigation methods (arrows, dots, thumbnails)
  • Test on mobile devices for touch interactions
dd.Mobile Considerations: The gallery automatically hides thumbnails on small screens and adjusts navigation elements for touch interfaces. Test your galleries on various device sizes.

Troubleshooting

Images Not Loading

  1. Check file paths are correct and start with / for local images
  2. Verify images exist in the static/ folder
  3. Ensure external image URLs are accessible
  4. Check browser console for 404 errors
  1. Verify unique id for each gallery on the same page
  2. Check JSON syntax in the images parameter
  3. Ensure JavaScript is enabled in browser
  4. Look for console errors

Styling Issues

  1. Check CSS custom properties are defined
  2. Verify theme compatibility
  3. Test in different browsers
  4. Clear browser cache after CSS changes

Integration with Hugo

The gallery slider integrates seamlessly with Hugo’s content management:

---
title: "My Gallery Post"
gallery_images:
  - src: "/images/gallery/image1.jpg"
    alt: "Description 1"
    caption: "Caption 1"
  - src: "/images/gallery/image2.jpg"
    alt: "Description 2"
    caption: "Caption 2"
---

# My Post with Gallery



    
No images provided for gallery "post-gallery". Use src1, src2, etc. parameters or define images in frontmatter.

  


More content here...

This approach allows you to define gallery images in frontmatter and reference them in your content, making management easier for large galleries.


This approach allows you to define gallery images in frontmatter and reference them in your content, making management easier for large galleries.