Image Carousel

Get the code
[su_image_carousel source="media: 34494,34495,34496,34497,34498,34500,34501,34503,34504" limit="20" slides_style="default" controls_style="dark" crop="16:9" columns="1" adaptive="yes" spacing="yes" align="none" max_width="none" captions="no" arrows="yes" dots="yes" link="lightbox" target="blank" autoplay="5" speed="medium" image_size="medium" class=""]

Table of contents

  1. Description
  2. Options
  3. Display image captions instead of post titles
    1. For a single shortcode
    2. For all shortcodes
  4. Adding custom links to slides
  5. Filtering slides query (WP_Query)


With this shortcode, you can easily create beautiful image sliders and carousels. Image Carousel was introduced in Shortcodes Ultimate version 5.4.0.


sourceThis option defines which images will be shown in the gallery. Images can be selected manually from media library or fetched automatically from post featured images, or even filtered by a taxonomy.

Possible values:
media: 1,2,3 (Media file IDs)
posts: 1,2,3 (Post IDs)
posts: recent (Recent posts)
taxonomy: category/3,5 (Taxonomy term slug / term IDs)

Default value: none
limitMaximum number of posts to search featured images in (for recent media, recent posts, and taxonomy)

Possible values: Number from -1 to 100

Default value: 20
slides_styleThis option control carousel slides appearance.

Possible values: default, minimal, photo

Default value: default
controls_styleThis option control carousel controls appearance.

Possible values: dark, light

Default value: dark
cropThis option allows to enable/disable image cropping and crop aspect ratio.

Possible values:
none (Do not crop images)
21:9 ([Landscape] 21:9)
16:9 ([Landscape] 16:9)
16:10 ([Landscape] 16:10)
5:4 ([Landscape] 5:4)
4:3 ([Landscape] 4:3)
3:2 ([Landscape] 3:2)
2:1 ([Landscape] 2:1)
1:1 ([Square] 1:1)
1:2 ([Portrait] 1:2)
2:3 ([Portrait] 2:3)
3:4 ([Portrait] 3:4)
4:5 ([Portrait] 4:5)
10:16 ([Portrait] 10:16)
9:16 ([Portrait] 9:16)
9:21 ([Portrait] 9:21)

Default value: 4:3
columnsThis option control the number of columns used in the carousel.

Possible values: Number from 1 to 8

Default value: 1
adaptiveSet this option to Yes to ignore the columns parameter and display a single column on mobile devices.

Possible values: yes or no

Default value: yes
spacingAdds spacing between carousel columns.

Possible values: yes or no

Default value: yes
alignThis option controls how the gallery will be aligned within a page. Left, Right, and Center options require Max Width to be set. Full option requires page template with no sidebar.

Possible values:

Default value: none
max_widthSets maximum width of the carousel container. CSS uints are allowed.
Example values: 500, 500px, 50%, 40rem.
Default value: none.

Default value: none
captionsSet this option to Yes to display image captions.

Possible values: yes or no

Default value: no
arrowsThis option enables left/right arrow navigation.

Possible values: yes or no

Default value: yes
dotsThis option enables dots/pages navigation.

Possible values: yes or no

Default value: yes
linkThis option adds links to carousel slides.

Possible values:
image (Full-size image)
custom (Custom link (added in media editor))
attachment (Attachment page)
post (Post permalink)

Default value: none
targetThis option controls how slide links will be opened.

Default value: blank
autoplaySets the time interval between automatic slide transitions, in seconds. Set to 0 to disable autoplay.

Possible values: Number from 0 to 15

Default value: 5
speedThis option control slides transition speed.

Possible values:

Default value: medium
image_sizeThis option controls the size of carousel slide images. This option only affects image quality, not the actual slide size.

Possible values:
full (Original image size)

Default value: large
outlineThis option enables outline when carousel gets focus. The outline improves keyboard navigation.

Possible values: yes or no

Default value: yes
randomThis option enables random order for selected images. Available since 5.9.3.

Possible values: yes or no

Default value: no
classAdditional CSS class name(s) separated by space(s)

Display image captions instead of post titles

Since plugin version 5.6.1 the Image Carousel shortcode uses post titles instead of image captions if the source is set to posts or taxonomy. Example:

[su_image_carousel source="posts: ..."]
[su_image_carousel source="taxonomy: ..."]

However, this behavior can be changed.

For a single shortcode

Add the prefer_caption attribute to your shortcode:

[su_image_carousel source="posts: ..." prefer_caption="yes"]

For all shortcodes

Add the following snippet to the end of the functions.php file of your active theme:

	function( $out, $pairs, $atts, $shortcode ) {
		$out['prefer_caption'] = 'yes';
		return $out;

The following screencast will show you how to add custom links to carousel slides.

Filtering slides query (WP_Query)

This part of the article is for advanced users. You can apply a custom filter to the WP_Query request used in Image Carousel to fine-tune the results. Use the su/get_gallery_slides_query filter to do that. Example:

	function( $args, $source, $atts ) {

		// $atts contains parsed attributes
		// Uncomment the next line to see what's inside
		// var_dump( $atts );

		// $source contains parsed images source attribute value
		// Uncomment the next line to see what's inside
		// var_dump( $source );

		// Do your modifications here...
		$args['order'] = 'ASC';

		// Return the modified args.
		// This data will be passed to the WP_Query constructor.
		return $args;


Photos by Matt Palmer

🤝 Thank you!