Skip to main content

FAQ: Widget Carousel for Confluence — Image Sliders, Banners & Dashboards

· 15 min read
NGPilot
NGPilot
NGPilot

Confluence pages are powerful containers for knowledge, documentation, and team collaboration. But when it comes to displaying visual content -- product screenshots, event photos, marketing banners, or process walkthroughs -- the standard page layout falls short. Images stacked vertically create long, scroll-heavy pages that are difficult to scan, and Confluence's built-in gallery macro only offers a static thumbnail grid with no interactive slideshow behavior.

Widget Carousel for Confluence solves this by adding a fully interactive image carousel macro that you can embed on any Confluence page. You select images from page attachments or upload new ones directly, then display them in a customizable slider with configurable width options. The result is a polished, professional-looking carousel that transforms how visual content is presented in your Confluence workspace.

This FAQ covers the most common questions teams have about Widget Carousel for Confluence -- from basic setup and content types to advanced configuration, responsive design, and how it compares to Confluence's native gallery macro. Whether you are building a company dashboard, a project landing page, or a team portal, this guide will help you get the most out of the carousel.

Widget Carousel for Confluence is an Atlassian Marketplace app that adds an interactive image carousel macro to your Confluence editor. Once installed, you can insert the macro on any page and configure it with images to create a professional slideshow display.

The app integrates directly into the Confluence editing experience. You insert the macro by typing /widget in the editor and selecting "Widget Carousel" from the dropdown, or by clicking the "+" insert button and choosing it from the macro browser. This follows the same pattern as other Confluence macros, so there is no learning curve for authors who are already familiar with the editor.

Once inserted, the macro presents a visual image picker that shows all attachments on the current page. You can select existing images or upload new ones directly through the picker interface. After selecting your images and clicking "Save," the carousel appears on the page ready to use. The entire setup process takes less than a minute for most configurations.

Widget Carousel supports three width configurations that control how much horizontal space the carousel occupies:

  • Default width -- The carousel fits within the standard Confluence content column, matching the width of regular page content. This is the best choice for carousels embedded within longer pages that also contain text, tables, or other macros.
  • Wide width -- The carousel extends beyond the standard content column to use more of the available page width. This works well for carousels that are the primary content on a page, such as a dashboard banner or a product showcase section.
  • Full width -- The carousel spans the entire width of the page, edge to edge. This is ideal for hero banners on landing pages or portal homepages where you want the carousel to be the dominant visual element.

You configure the width using the macro edit buttons that appear when you select the macro in the editor. This is the same interface Confluence uses for other width-aware macros, keeping the experience consistent.

The carousel renders with smooth transitions between slides, navigation controls for moving forward and backward through the image sequence, and a clean visual design that integrates with Confluence's page styling. For a detailed walkthrough of the setup process, see the Widget Carousel usage documentation.

Confluence ships with a built-in gallery macro that many users discover first when looking for image display options. Understanding the differences between the gallery macro and Widget Carousel helps you choose the right tool for each use case.

Layout model. The built-in gallery macro arranges images in a static grid of thumbnails. You configure the number of columns, and Confluence places each image into a cell in the grid. Users click individual thumbnails to open a lightbox overlay where they can browse through the full-size images. Widget Carousel takes a fundamentally different approach: it displays one image (or a defined set of images) at a time in a horizontal slider, with smooth transitions between slides. The carousel format is inherently sequential, guiding the viewer through images in order.

Width and layout control. The gallery macro renders within the standard content column with basic column count configuration. Widget Carousel offers three distinct width modes (default, wide, full width) that give you precise control over how the carousel integrates with the page layout. For pages where the image display needs to be a prominent visual element rather than an inline content block, the wide and full-width options provide layout flexibility that the gallery macro cannot match.

Interactivity. The gallery macro's interactivity is limited to clicking a thumbnail to open the lightbox. There is no timed transitions and no sequential navigation within the page itself -- the browsing happens in the lightbox overlay. Widget Carousel provides on-page navigation controls that let users move through slides without leaving the page context.

Use case fit. The gallery macro works well for photo albums, design review collections, and any scenario where users need to browse a large number of images independently. Widget Carousel is the better choice when images need to be presented as a narrative sequence -- product feature walkthroughs, process step illustrations, announcement rotations, or any context where the order and progression of images matters.

Setup workflow. The gallery macro uses a file pattern or label filter to pull in all matching attachments from the page. Widget Carousel uses an explicit image picker where you select specific images in a specific order. The picker approach gives you more control over which images appear and in what sequence, at the cost of needing to manually select each image rather than relying on automatic filtering.

In practice, many teams use both: the gallery macro for general image collections and Widget Carousel for featured displays, banners, and sequential presentations.

What content types can I display in a Widget Carousel?​

Widget Carousel is focused on image content, supporting the most common image formats used in Confluence environments.

Supported image formats:

  • JPEG (.jpg, .jpeg) -- The most common format for photographs and screenshots. JPEG images work well for product photos, team pictures, and any content with complex color gradients.
  • PNG (.png) -- Ideal for screenshots, diagrams, and images with text overlays. PNG supports transparency, which allows images to blend cleanly with different background colors.
  • GIF (.gif) -- Supports simple animations. Animated GIFs play their animation cycle within the carousel, adding motion to your image displays.
  • SVG (.svg) -- Scalable vector graphics that render crisply at any size. SVG is a strong choice for logos, icons, diagrams, and any visual content that needs to look sharp at both small and large display sizes.

Image source options:

  • Page attachments -- The primary source for carousel images. When you open the macro configuration, the image picker displays all files currently attached to the Confluence page. You can select any image attachment to include it in the carousel.
  • Upload during configuration -- If the image you need is not yet attached to the page, you can upload it directly through the macro configuration interface. The upload adds the file as a page attachment and includes it in the carousel in one step, without needing to navigate to a separate attachment management screen.

Preparing images for best results:

  • Consistent dimensions -- Images with the same aspect ratio produce the most polished carousel display. When images have different aspect ratios, the carousel adapts, but consistent sizing creates a smoother visual experience.
  • Optimized file sizes -- Large image files slow down page load times. Resize images to the display dimensions you need before uploading, and use JPEG compression for photographs. Confluence's built-in image handling helps, but starting with optimized files produces the fastest results.
  • Descriptive file names -- Use clear, descriptive file names for your images. This helps team members identify the correct images when configuring the carousel and makes attachment management easier over time.

Content strategies for effective carousels:

  • Product feature highlights -- Create a series of annotated screenshots that walk through key features, with each slide focusing on one feature.
  • Event photo galleries -- Curate the best photos from team events, conferences, or company milestones into a sequential display.
  • Process walkthroughs -- Use step-by-step screenshots to illustrate workflows, onboarding procedures, or technical processes where each slide represents one step.
  • Announcement rotations -- Design visual announcement cards (using a consistent template) and rotate through them on dashboard pages.

Widget Carousel renders navigation elements that allow users to move through the image sequence. The controls are designed to be intuitive and unobtrusive -- visible enough to discover but not so prominent that they distract from the image content itself. Users can move forward and backward through the slides, giving them full control over the viewing pace.

Configuration workflow:

Navigation and display settings are configured through the macro editor. You insert the Widget Carousel macro, select your images, and configure the layout before saving. The settings apply to that specific macro instance, so you can have different carousel configurations on different pages or even multiple carousels with different settings on the same page.

Responsive design is critical for Confluence pages because your team accesses content from a range of devices -- desktop workstations, laptops, tablets, and mobile phones. Widget Carousel is built to adapt to different screen sizes and container dimensions.

Width adaptation:

The three width modes (default, wide, full width) determine the starting container size, and the carousel scales proportionally within that container. On wider screens, the carousel takes full advantage of the available space. On narrower screens, it compresses gracefully while maintaining image aspect ratios and navigation functionality.

  • Default width carousels scale with the Confluence content column, which itself adapts to the viewport. This produces consistent behavior across devices.
  • Wide and full-width carousels expand to use more horizontal space on desktop but compress appropriately on smaller screens, ensuring that images remain fully visible without horizontal scrolling.

Image scaling:

Images within the carousel are scaled to fit the carousel container while preserving their aspect ratio. This means images are never stretched or distorted regardless of the screen size. On smaller screens, images appear at a reduced size but maintain their visual integrity.

Navigation control scaling:

The navigation controls scale with the carousel to remain accessible on touch devices. Tapping navigation elements on a tablet or phone works the same as clicking them on a desktop. The touch target sizes are designed to meet mobile usability standards, so navigation does not require precise tapping.

Confluence theme compatibility:

Widget Carousel renders within Confluence's standard macro container, which means it respects the active Confluence theme. Whether your instance uses the default Confluence theme, a custom theme, or a third-party theme, the carousel integrates with the surrounding page design rather than appearing as an isolated element.

Performance on mobile networks:

Since the carousel displays images from page attachments, Confluence's built-in CDN and caching infrastructure handle image delivery. This means images are served efficiently on mobile networks, with appropriate caching to minimize redundant downloads on repeat visits.

Widget Carousel shines in scenarios where sequential image display creates a better user experience than static layouts. Here are the most effective use cases we see teams deploying.

Team dashboards with rotating banners:

Many Confluence spaces serve as team dashboards -- central pages where team members check for updates, announcements, and key metrics. A carousel at the top of the dashboard can rotate through:

  • Sprint goals and current status visuals
  • Team announcements and upcoming events
  • Key performance indicator charts and graphs
  • Recognition highlights and team achievements

The carousel format keeps the content organized so that repeat visitors can browse through different highlights. This approach keeps dashboards feeling dynamic without requiring frequent manual updates to the page layout.

Project landing pages and product showcases:

When you create a Confluence page to introduce a project, product, or initiative, visual impact matters. A full-width carousel at the top of the page can display:

  • Product screenshots highlighting key features
  • Architecture diagrams showing system design
  • User interface mockups for design reviews
  • Timeline graphics showing project milestones

The sequential nature of the carousel lets you tell a visual story -- guiding viewers through features in a logical order rather than presenting them all at once in an overwhelming grid.

Onboarding and training portals:

Confluence is widely used for employee onboarding and internal training. Widget Carousel enhances these pages by presenting step-by-step visual guides:

  • Software walkthrough screenshots where each slide shows one step
  • Office orientation photos for new employee guides
  • Process diagrams that build progressively across slides
  • Safety training visuals for compliance documentation

The navigation controls let new employees move through the content at their own pace, and the carousel format keeps the page compact compared to displaying all images simultaneously.

Company intranet and portal pages:

For organizations using Confluence as an intranet platform, Widget Carousel adds a professional visual element to portal pages:

  • Company news and announcement banners
  • Event photo highlights from recent activities
  • Employee spotlight features with photos and bios
  • Cultural value illustrations and mission statement visuals

The carousel format mirrors the visual banner pattern that users expect from modern intranet homepages, bringing that familiar experience into the Confluence environment.

Documentation and knowledge base enhancement:

Even in traditional documentation contexts, carousels add value when used strategically:

  • Before-and-after comparisons in change documentation
  • Version history screenshots showing UI evolution
  • Troubleshooting guides with sequential diagnostic screenshots
  • Release note highlights with annotated feature screenshots

Follow these steps to add a carousel to any Confluence page:

  1. Insert the macro -- Type /widget in the Confluence editor and select "Widget Carousel" from the dropdown, or click the "+" button and choose "Widget Carousel" from the insert menu.
  2. Select images -- Use the image picker to select images from existing page attachments, or upload new images directly through the picker interface.
  3. Save the macro -- Click "Save" on the macro configuration to confirm your image selection.
  4. Configure width -- Use the macro edit buttons to set the width: default, wide, or full width, depending on how prominent you want the carousel to be on the page.
  5. Save the page -- Save or publish the Confluence page to see the carousel rendered live.

The entire process takes under a minute for most configurations. See the full usage guide for detailed instructions with screenshots.

FeatureWidget CarouselBuilt-in Gallery Macro
Display formatHorizontal slider / carouselStatic thumbnail grid
Image navigationSequential with transitionsClick-to-open lightbox
Width configurationDefault, wide, full widthStandard content column
Image selectionVisual picker (explicit selection)File pattern or label filter
Order controlManual, explicit orderingAlphabetical by filename
Use case focusFeatured displays, banners, narrativesImage collections, photo albums

Standardize your image dimensions. Carousels look most professional when all slides have consistent dimensions. Create a template canvas size for your team and resize all carousel images to match before uploading. Common choices include 1200x600 for banner-style carousels and 800x600 for standard content carousels.

Design for the slide format. Each slide in the carousel is displayed individually, which means each image needs to stand on its own. Add clear titles, annotations, or captions directly to the images if the visual needs context. Avoid splitting a single concept across multiple slides unless the progression is self-explanatory.

Limit the number of slides. Carousels with too many images become difficult to navigate and can overwhelm viewers. Aim for 5 to 10 slides for most use cases. If you need to display more images, consider splitting them across multiple carousels organized by category or theme.

Use full-width mode for landing pages. When the carousel is the primary visual element on a page -- such as a project landing page or team portal -- the full-width configuration creates the most impact. For carousels embedded within content-heavy pages, stick with the default width to maintain page flow.

Keep file sizes reasonable. Large images slow down page loads, especially for carousels with many slides. Optimize images before uploading by resizing to the display dimensions and compressing JPEG files. This is particularly important for dashboards and portal pages that team members load frequently.

Pair with other macros for rich pages. Widget Carousel works well alongside other Confluence macros. Combine a carousel banner at the top of a page with text sections, tables, and other macros below to create comprehensive, visually engaging pages.