Image Carousel

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)

Description

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

Options

source	This 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
limit	Maximum 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_style	This option control carousel slides appearance. Possible values: default, minimal, photo Default value: default
controls_style	This option control carousel controls appearance. Possible values: dark, light Default value: dark
crop	This 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
columns	This option control the number of columns used in the carousel. Possible values: Number from 1 to 8 Default value: 1
adaptive	Set 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
spacing	Adds spacing between carousel columns. Possible values: yes or no Default value: yes
align	This 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: none left right center full Default value: none
max_width	Sets maximum width of the carousel container. CSS uints are allowed. Example values: 500, 500px, 50%, 40rem. Default value: none. Default value: none
captions	Set this option to Yes to display image captions. Possible values: yes or no Default value: no
arrows	This option enables left/right arrow navigation. Possible values: yes or no Default value: yes
dots	This option enables dots/pages navigation. Possible values: yes or no Default value: yes
link	This option adds links to carousel slides. Possible values: none image (Full-size image) lightbox custom (Custom link (added in media editor)) attachment (Attachment page) post (Post permalink) Default value: none
target	This option controls how slide links will be opened. Default value: blank
autoplay	Sets 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
speed	This option control slides transition speed. Possible values: immediate fast medium slow Default value: medium
image_size	This 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) thumbnail medium medium_large large Default value: large
outline	This option enables outline when carousel gets focus. The outline improves keyboard navigation. Possible values: yes or no Default value: yes
random	This option enables random order for selected images. Available since 5.9.3. Possible values: yes or no Default value: no
class	Additional 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:

add_filter(
	'shortcode_atts_image_carousel',
	function( $out, $pairs, $atts, $shortcode ) {
		$out['prefer_caption'] = 'yes';
		return $out;
	},
	10,
	4
);

Adding custom links to slides

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:

add_filter(
	'su/get_gallery_slides_query',
	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;

	},
	10,
	3
);

---

Photos by Matt Palmer