Looking for an elegant way to showcase multiple images in your blog posts? Our custom Carousel component makes it easy to create beautiful, interactive image galleries with smooth transitions and intuitive navigation. Perfect for photo galleries, product showcases, portfolios, and more!
🎠 Carousel Component
What is the Carousel Component?
The Carousel is a React component that displays images in a slideshow format, featuring:
- Smooth transitions - Beautiful fade in/out animations between slides
- Navigation arrows - Previous/Next controls with hover effects
- Dot indicators - Visual markers showing current slide and total slides
- Click navigation - Navigate through slides with arrow clicks or dot selection
- Customizable height - Adjust carousel height to fit your needs
- Responsive design - Centered layout with automatic margins
- Auto-sized images - Images scale to fill the carousel while maintaining aspect ratio
- Accessible - Proper alt text support for screen readers
📦 Importing Carousel
import { Carousel } from '@/react/Carousel';or with relative path:
import { Carousel } from '../../react/Carousel';Important: Always use the
.mdxfile extension (not.md) when working with React components in your blog posts.
🎯 Carousel Usage
Basic Carousel
Code Example:
<Carousel client:load images={[ { src: '/images/photo1.jpg', alt: 'Description of photo 1' }, { src: '/images/photo2.jpg', alt: 'Description of photo 2' }, { src: '/images/photo3.jpg', alt: 'Description of photo 3' }3 collapsed lines
]} height="600px"/>Note: The
client:loaddirective is required for the Carousel component to work properly in Astro/MDX files. This enables React hydration for interactivity.
Design Credit: Book card design inspired by Codepen - Pure CSS Carousel1
🎨 Carousel Features
- Image Slides: Display multiple images in sequence
- Smooth Transitions: 0.7s fade animations between slides
- Navigation Controls: Large, semi-transparent arrows (‹ and ›)
- Hover Effects: Controls become fully opaque on hover
- Dot Indicators: White circular dots at the bottom
- Active State: Current slide’s dot is fully opaque
- Click Navigation: Click arrows or dots to change slides
- Automatic Centering: 15% margins on left and right
⚙️ Props
images- Array of image objects (required)- Each object must have:
src(string) andalt(string)
- Each object must have:
height- Carousel height as CSS string (defaults to'600px')client:load- Astro directive to enable interactivity (required)
Image Object Structure
{ src: string, // Image URL or path (required) alt: string // Alt text for accessibility (optional but recommended)}📐 Customizing Height
You can adjust the carousel height to fit your content:
Compact Carousel (400px):
<Carousel client:load images={[...]} height="400px"/>Tall Carousel (800px):
<Carousel client:load images={[...]} height="800px"/>Auto Height (full screen):
<Carousel client:load images={[...]} height="100vh"/>🎯 Use Cases
Photo Gallery
Perfect for showcasing a collection of related images:
<Carousel client:load images={[ { src: '/gallery/vacation-1.jpg', alt: 'Beach sunset' }, { src: '/gallery/vacation-2.jpg', alt: 'Mountain view' }, { src: '/gallery/vacation-3.jpg', alt: 'City skyline' }, { src: '/gallery/vacation-4.jpg', alt: 'Forest trail' } ]}/>Product Showcase
Display multiple views of a product:
<Carousel client:load images={[ { src: '/products/front-view.jpg', alt: 'Product front view' }, { src: '/products/side-view.jpg', alt: 'Product side view' }, { src: '/products/back-view.jpg', alt: 'Product back view' }, { src: '/products/detail-view.jpg', alt: 'Product detail closeup' } ]} height="500px"/>Portfolio Display
Show off your work with style:
<Carousel client:load images={[ { src: '/portfolio/project1.jpg', alt: 'Web design project' }, { src: '/portfolio/project2.jpg', alt: 'Mobile app interface' }, { src: '/portfolio/project3.jpg', alt: 'Logo design' } ]} height="700px"/>Before & After
Compare transformations:
<Carousel client:load images={[ { src: '/renovation/before.jpg', alt: 'Kitchen before renovation' }, { src: '/renovation/after.jpg', alt: 'Kitchen after renovation' } ]}/>💡 Tips for Best Results
- Optimize images - Compress images for web (recommended max width: 1920px)
- Consistent dimensions - Use images with similar aspect ratios for best results
- Descriptive alt text - Always provide meaningful alt text for accessibility
- Appropriate height - Choose height based on your images (landscape vs portrait)
- Minimum slides - Use at least 2 images for carousel functionality
- Loading performance - Consider lazy loading for carousels with many images
- File formats - Use WebP for better compression, with JPG/PNG fallbacks
- Mobile considerations - Test on mobile devices to ensure images display well
- Navigation visibility - Ensure arrow controls are visible against image backgrounds
- Context matters - Use carousels for related content, not random images
🎨 Styling Details
The carousel includes built-in styling:
- Margins: 15% on left and right for centered display
- Background: Images cover full carousel area with
object-fit: cover - Controls: Font size 100px, white color, semi-transparent
- Dots: 30px circles, white, positioned 20px from bottom
- Transitions: 0.7s ease-in-out for smooth slide changes
- Hover: Controls opacity changes from 0.5 to 1.0
♿ Accessibility
- ✅ Alt text support for all images
- ✅ Clickable navigation controls
- ✅ Visual indicators for current slide
- ✅ Semantic HTML structure
- ✅ Keyboard-friendly (click-based navigation)
🌐 Browser Compatibility
Works in all modern browsers supporting:
- CSS Transitions
- ES6+ JavaScript
- React 16.8+ (Hooks)
⚠️ Important Notes
- Client directive required: Must use
client:loadin Astro/MDX - Images array required: Component returns null if images array is empty
- Alt text recommended: Provide descriptive alt text for each image
- Height customization: Default height is 600px, adjust as needed
- Image optimization: Large images may impact page load performance
🐛 Troubleshooting
Carousel not working?
- Ensure
client:loaddirective is present - Check that images array is properly formatted
- Verify image URLs are accessible
Images not displaying?
- Check image paths/URLs are correct
- Verify images are publicly accessible
- Check browser console for loading errors
Controls not visible?
- Ensure images are loading properly
- Check if controls are covered by other elements
- Verify z-index settings aren’t conflicting
Transitions not smooth?
- Check browser compatibility
- Ensure no conflicting CSS transitions
- Verify React is properly hydrated
📚 Complete Example
Here’s a complete example combining everything:
---title: My Photo Gallery---
import { Carousel } from '@/react/Carousel';
## My Travel Photos
Check out these amazing photos from my recent trip!
<Carousel client:load images={[ { src: '/travel/paris.jpg',19 collapsed lines
alt: 'Eiffel Tower at sunset' }, { src: '/travel/rome.jpg', alt: 'Colosseum in Rome' }, { src: '/travel/tokyo.jpg', alt: 'Tokyo skyline at night' }, { src: '/travel/sydney.jpg', alt: 'Sydney Opera House' } ]} height="600px"/>
Use the arrows or dots to navigate through the images!🎉 Conclusion
The Carousel component provides an elegant solution for displaying multiple images in your blog posts. With smooth transitions, intuitive controls, and full customization options, it’s perfect for galleries, portfolios, product showcases, and more.
Key Takeaways:
- ✅ Easy to implement with simple
imagesprop - ✅ Smooth, professional transitions
- ✅ Fully accessible with alt text support
- ✅ Customizable height for any use case
- ✅ Works seamlessly in Astro/MDX with
client:load
Start creating beautiful image galleries in your blog posts today! 🚀