syncfusion-aspnetcore-carousel

# Implementing Syncfusion ASP.NET Core Carousel Component The Carousel component displays a set of slides with support for automatic transitions, touch/mouse swiping, customizable animations, and various indicator styles. It's ideal for image galleries, content rotators, testimonials, and any scenario requiring sequential content presentation. ## When to Use This Skill Use this skill when you need to: - **Create an image carousel or gallery** – Display multiple images or content items that users can browse - **Implement automatic slide transitions** – Show rotating content with configurable intervals and animations - **Add navigation controls** – Enable manual navigation with previous/next buttons and interactive indicators - **Handle slide change events** – Track when slides change and respond with custom logic - **Support touch and mouse interactions** – Enable swipe gestures on mobile and mouse drag on desktop - **Customize animation effects** – Apply fade, slide, or custom CSS animations during transitions - **Optimize performance** – Load images in modern WebP format and manage carousel state persistence - **Build accessible slideshows** – Implement keyboard navigation and proper ARIA support ## Component Overview The Carousel component consists of: - **Carousel container** (`<ejs-carousel>`) – Main component wrapper - **Carousel items** (`<e-carousel-item>`) – Individual slide elements - **Navigation buttons** – Previous/next controls with customizable templates - **Indicators** – Visual indicators showing current position (dots, dynamic, fraction, or progress) - **Play/Pause controls** – Optional playback control UI - **Event system** – Slide changing and slide changed events for custom logic ## Key Concepts - **Auto-play** – Automatically transitions between slides at specified intervals - **Looping** – Allows continuous cycling from last slide back to first - **Animation effects** – Built-in Slide and Fade effects, plus custom CSS animations - **Partial visible slides** – Shows adjacent slide previews alongside the active slide - **Swipe modes** – Independent control of touch and mouse swiping interactions - **Item templates** – Individual templates per item or a common template for all items - **Data binding** – Populate carousel from data source or declarative item markup ## Documentation and Navigation Guide ### Getting Started 📄 **Read:** [references/getting-started.md](references/getting-started.md) - Install NuGet packages (Syncfusion.EJ2.AspNet.Core) - Register Tag Helper in `_ViewImports.cshtml` - Add stylesheet and script resources (CDN or local) - Create your first basic carousel with template items - Verify rendering and initial setup ### Populating Items and Data Binding 📄 **Read:** [references/populating-items.md](references/populating-items.md) - Populate items using carousel item markup (`<e-carousel-item>`) - Populate items using data source binding with `itemTemplate` - Set `selectedIndex` to start at a specific slide - Show partial visible slides with adjacent slide previews - Customize per-item template or interval duration ### Animations and Transitions 📄 **Read:** [references/animations-transitions.md](references/animations-transitions.md) - Configure animation effects (None, Slide, Fade, Custom) - Set slide transition intervals (milliseconds) - Enable/disable auto-play and pause-on-hover behavior - Control looping behavior at the end of slides - Disable touch swipe and configure swipe modes - Handle slide changing and slide changed events ### Navigation Controls and Indicators 📄 **Read:** [references/navigation-indicators.md](references/navigation-indicators.md) - Show/hide navigation buttons (Hidden, Visible, VisibleOnHover) - Customize navigation button templates - Configure indicator types (Default, Dynamic, Fraction, Progress) - Customize indicator templates and previews - Enable/disable play/pause button controls - Customize play button template ### Performance and Optimization 📄 **Read:** [references/optimization.md](references/optimization.md) - Load images in WebP format for better performance - Enable state persistence across page reloads - Configure RTL rendering for right-to-left languages - Apply CSS class customization - Optimize data source binding for large datasets ### API Reference 📄 **Read:** [references/api-reference.md](references/api-reference.md) - Complete property reference with descriptions and types - Event arguments and event handling patterns - Enumeration types and allowed values - TagHelper attribute mapping - HTML attributes support ## Quick Start Example ```html <div class="carousel-container"> <ejs-carousel id="basicCarousel" autoPlay="true" animationEffect="Slide" buttonsVisibility="Visible" showIndicators="true"> <e-carousel-items> <e-carousel-item template="#slide1"></e-carousel-item> <e-carousel-item template="#slide2"></e-carousel-item> <e-carousel-item template="#slide3"></e-carousel-item> </e-carousel-items> </ejs-carousel> </div> <script id="slide1" type="text/x-template"> <img src="/images/slide1.jpg" alt="Slide 1" style="height: 100%; width: 100%;" /> </script> <script id="slide2" type="text/x-template"> <img src="/images/slide2.jpg" alt="Slide 2" style="height: 100%; width: 100%;" /> </script> <script id="slide3" type="text/x-template"> <img src="/images/slide3.jpg" alt="Slide 3" style="height: 100%; width: 100%;" /> </script> <style> .carousel-container { max-width: 600px; height: 400px; margin: 20px auto; } </style> ``` ## Common Implementation Patterns ### Pattern 1: Image Gallery with Auto-Play Create an automatic image carousel that cycles through slides and pauses on user hover: ```html <ejs-carousel id="photoGallery" autoPlay="true" pauseOnHover="true" interval="3000"> <e-carousel-items> <e-carousel-item template="#photo1"></e-carousel-item> <e-carousel-item template="#photo2"></e-carousel-item> </e-carousel-items> </ejs-carousel> ``` ### Pattern 2: Manual Navigation with Custom Indicators Create a carousel with manual navigation and custom indicator styling: ```html <ejs-carousel id="manualCarousel" autoPlay="false" buttonsVisibility="Visible" showIndicators="true" indicatorsType="Fraction"> <e-carousel-items> <e-carousel-item template="#item1"></e-carousel-item> <e-carousel-item template="#item2"></e-carousel-item> </e-carousel-items> </ejs-carousel> ``` ### Pattern 3: Data-Bound Carousel Populate carousel from a data source with uniform template: ```html <ejs-carousel id="dataCarousel" dataSource="@Model.Slides" itemTemplate="#itemTemplate"> </ejs-carousel> <script id="itemTemplate" type="text/x-template"> <div class="slide-content"> <img src="${image}" alt="${title}" style="height: 100%; width: 100%;" /> <h3>${title}</h3> </div> </script> ``` ### Pattern 4: Event-Driven Slide Tracking Handle slide transitions and track user interactions: ```html <ejs-carousel id="trackedCarousel" slideChanging="onSlideChanging" slideChanged="onSlideChanged"> <e-carousel-items> <e-carousel-item template="#slide1"></e-carousel-item> </e-carousel-items> </ejs-carousel> <script> function onSlideChanging(args) { console.log('Moving from slide ' + args.currentIndex + ' to ' + args.nextIndex); } function onSlideChanged(args) { console.log('Now on slide ' + args.currentIndex); } </script> ``` ## Key Properties | Property | Type | Purpose | Common Values | |----------|------|---------|----------------| | `autoPlay` | boolean | Enable automatic slide transitions | true, false | | `interval` | number | Milliseconds between auto-transitions | 5000, 3000 | | `animationEffect` | enum | Transition animation type | Slide, Fade, None, Custom | | `buttonsVisibility` | enum | Navigation button visibility | Visible, Hidden, VisibleOnHover | | `showIndicators` | boolean | Display slide position indicators | true, false | | `indicatorsType` | enum | Indicator style | Default, Dynamic, Fraction, Progress | | `loop` | boolean | Cycle from last slide to first | true, false | | `pauseOnHover` | boolean | Pause auto-play when hovering | true, false | | `enableTouchSwipe` | boolean | Enable swipe on touch devices | true, false | | `selectedIndex` | number | Initial slide index | 0, 1, 2... | | `partialVisible` | boolean | Show adjacent slide previews | true, false | ## Common Use Cases - **E-Commerce Product Showcase** – Display product images with navigation - **Blog or Portfolio Gallery** – Showcase projects or articles sequentially - **Testimonials Carousel** – Rotate customer testimonials automatically - **Advertisements/Promotions** – Cycle promotional banners - **Hero Sections** – Full-width rotating content on landing pages - **News/Updates Feed** – Display latest news items in rotating carousel - **Social Media Feeds** – Show image posts in carousel format ## Browser Support The Carousel component works in all modern browsers: - Chrome/Edge (latest) - Firefox (latest) - Safari (latest) - Mobile browsers (iOS Safari, Chrome Android) ## Performance Tips - Use WebP images for better performance - Set appropriate `interval` values to reduce CPU usage - Disable auto-play if not needed - Use `partialVisible: false` to reduce rendering overhead - Consider lazy-loading images for large galleries ## Next Steps 1. Start with [Getting Started](references/getting-started.md) to set up your environment 2. Choose your use case from the patterns above 3. Review the relevant reference section for your features 4. Check [API Reference](references/api-reference.md) for complete property documentation 5. Handle events as needed for your scenario --- **Need more help?** Check individual reference files for detailed examples and advanced configurations.