Advanced Custom Fields Image Object Tutorial

Update (10/11/2016): I added some escaping to the examples. Better safe than sorry.

When creating an image custom field in Advanced Custom Fields, it gives you the option of setting the “Return Value” as an “Image Object”.

Advanced Custom Field Adding an Image Screen

If you choose the “Image Object”,  get_field() will get a multidimensional array with all of the image’s values in it (instead of just the URL for the full size version, or the attachment ID), which will look something like this:

PHP

$imageArray = get_field('image_field'); var_dump($imageArray); /* output: array(9) { ["id"]=>int(5) ["alt"]=>string(4) "Test" ["title"]=>string(2) "29" ["caption"]=>string(0) "" ["description"]=>string(0) "" ["url"]=>string(67) "http://localhost:8888/site/wp-content/uploads/2013/10/29.jpg" ["width"]=>int(1280) ["height"]=>int(960) ["sizes"]=>array(18) { ["thumbnail"]=>string(75) "http://localhost:8888/site/wp-content/uploads/2013/10/29-150x150.jpg" ["thumbnail-width"]=>int(150) ["thumbnail-height"]=>int(150) ["medium"]=>string(75) "http://localhost:8888/site/wp-content/uploads/2013/10/29-300x225.jpg" ["medium-width"]=>int(300) ["medium-height"]=>int(225) ["large"]=>string(76) "http://localhost:8888/site/wp-content/uploads/2013/10/29-1024x768.jpg" ["large-width"]=>int(1024) ["large-height"]=>int(768) ["bones-thumb-600"]=>string(75) "http://localhost:8888/site/wp-content/uploads/2013/10/29-600x150.jpg" ["bones-thumb-600-width"]=>int(600) ["bones-thumb-600-height"]=>int(150) ["bones-thumb-300"]=>string(75) "http://localhost:8888/site/wp-content/uploads/2013/10/29-300x100.jpg" ["bones-thumb-300-width"]=>int(300) ["bones-thumb-300-height"]=>int(100) ["post-thumbnail"]=>string(75) "http://localhost:8888/site/wp-content/uploads/2013/10/29-125x125.jpg" ["post-thumbnail-width"]=>int(125) ["post-thumbnail-height"]=>int(125) } } */

1. $imageArray = get_field('image_field');

2. var_dump($imageArray);

3. /* output:

4. array(9) {

5.     ["id"]=>int(5)

6.     ["alt"]=>string(4) "Test"

7.     ["title"]=>string(2) "29"

8.     ["caption"]=>string(0) ""

9.     ["description"]=>string(0) ""

10.     ["url"]=>string(67) "http://localhost:8888/site/wp-content/uploads/2013/10/29.jpg"

11.     ["width"]=>int(1280)

12.     ["height"]=>int(960)

13.     ["sizes"]=>array(18) {

14.         ["thumbnail"]=>string(75) "http://localhost:8888/site/wp-content/uploads/2013/10/29-150x150.jpg"

15.         ["thumbnail-width"]=>int(150)

16.         ["thumbnail-height"]=>int(150)

17.         ["medium"]=>string(75) "http://localhost:8888/site/wp-content/uploads/2013/10/29-300x225.jpg"

18.         ["medium-width"]=>int(300)

19.         ["medium-height"]=>int(225)

20.         ["large"]=>string(76) "http://localhost:8888/site/wp-content/uploads/2013/10/29-1024x768.jpg"

21.         ["large-width"]=>int(1024)

22.         ["large-height"]=>int(768)

23.         ["bones-thumb-600"]=>string(75) "http://localhost:8888/site/wp-content/uploads/2013/10/29-600x150.jpg"

24.         ["bones-thumb-600-width"]=>int(600)

25.         ["bones-thumb-600-height"]=>int(150)

26.         ["bones-thumb-300"]=>string(75) "http://localhost:8888/site/wp-content/uploads/2013/10/29-300x100.jpg"

27.         ["bones-thumb-300-width"]=>int(300)

28.         ["bones-thumb-300-height"]=>int(100)

29.         ["post-thumbnail"]=>string(75) "http://localhost:8888/site/wp-content/uploads/2013/10/29-125x125.jpg"

30.         ["post-thumbnail-width"]=>int(125)

31.         ["post-thumbnail-height"]=>int(125)

32.     }

33. }

34. */

As you can see, this is a lot of information, which means, power! You can now use all that information to properly display that image in your templates.

To get a specific value, for example the ‘alt’, and ‘thumbnail’ size, you would have the following code:

HTML

<?php $imageArray = get_field('image_field'); // Array returned by Advanced Custom Fields $imageAlt = esc_attr($imageArray['alt']); // Grab, from the array, the 'alt' $imageThumbURL = esc_url($imageArray['sizes']['thumbnail']); //grab from the array, the 'sizes', and from it, the 'thumbnail' ?> <div><img src="<?php echo $imageThumbURL;?>" alt="<?php echo $imageAlt; ?>"></div>

1. <?php

3.  $imageArray = get_field('image_field'); // Array returned by Advanced Custom Fields

4.  $imageAlt = esc_attr($imageArray['alt']); // Grab, from the array, the 'alt'

5.  $imageThumbURL = esc_url($imageArray['sizes']['thumbnail']); //grab from the array, the 'sizes', and from it, the 'thumbnail'

6.  ?>

8.  <div><img src="<?php echo $imageThumbURL;?>" alt="<?php echo $imageAlt; ?>"></div>

If, for example, you wanted to do a lightbox with your images, you would do this:

HTML

<?php $imageArray = get_field('image_field'); // Array returned by Advanced Custom Fields $imageAlt = esc_attr($imageArray['alt']); // Grab, from the array, the 'alt' $imageURL = esc_url($imageArray['url']); // Grab the full size version $imageThumbURL = esc_url($imageArray['sizes']['thumbnail']); //grab from the array, the 'sizes', and from it, the 'thumbnail' ?> <a href="<?php echo $imageURL; ?>"> <img src="<?php echo $imageThumbURL;?>" alt="<?php echo $imageAlt; ?>"> </a>

1. <?php

3.  $imageArray = get_field('image_field'); // Array returned by Advanced Custom Fields

4.  $imageAlt = esc_attr($imageArray['alt']); // Grab, from the array, the 'alt'

5.  $imageURL = esc_url($imageArray['url']); // Grab the full size version 

6.  $imageThumbURL = esc_url($imageArray['sizes']['thumbnail']); //grab from the array, the 'sizes', and from it, the 'thumbnail'

7.  ?>

9.  <a href="<?php echo $imageURL; ?>">

10.     <img src="<?php echo $imageThumbURL;?>" alt="<?php echo $imageAlt; ?>">

11. </a>

15 Responses to “Advanced Custom Fields Image Object Tutorial”

1. Alex Vasquez March 5th, 2014

   Seriously? This post totally helped me out of a jam! Was trying to return the Image ID of an ACF field. I knew I needed to set the return Value as an Object; but my syntax was off; this post sorted me out. Double hyper extra yay!

   • Alicia Ramirez March 5th, 2014

     Glad I could help! Thanks for the ping back.

     • Alex Vasquez March 5th, 2014

       It’s funny because I was looking this up just yesterday! And that’s when your article posted. Crazy.

       Hey, btw, there are a couple of good WP FB groups, if interested:
       https://www.facebook.com/groups/OCWordPress/ and https://www.facebook.com/groups/advancedwp/

       You should join up. Tell em Alex sent ya.

       • Alicia Ramirez March 5th, 2014

         Haha! I know! I was surprised when I saw that your comment was not spam, since I had just started the blog, and posted that tutorial.

         I’ll check those facebook groups. Thanks.

2. Tamas Antal March 9th, 2014

   Awesome!
   Pointed me to the right direction 🙂 You should definitely offer ACF to write his original documentation. I still don’t believe that such a useful tip has not even been scratched there…
   Thanks!

3. Web site design company @Calgary March 15th, 2014

   Thank you so much for the great tutorial! It helped me out of a situation and I spent a large time trying to figure out ACF!

4. Sarah Tebo May 4th, 2014

   Huge thanks! I’m brand new to ACF and this helped me bunches. I was really confused on how to grab a particular size of an image, then link it to a larger size. You cleared that right up.

   • Alicia Ramirez May 4th, 2014

     You’re welcome!

5. pierre July 11th, 2014

   Thank you so much for this usefull tips!

6. Robert July 18th, 2014

   Ahh… i’ve been trying to figure this out for two days – thanks!

7. Cooler Websites August 24th, 2014

   Has anyone found a solution to get this working with ACF Repeater plugin?

   • Alicia Ramirez August 25th, 2014

     I think the Advanced Loop example in the Repeater Documentation does what you want.

8. kikaweb February 24th, 2015

   Thanks so much for posting this tutorial!

9. Debbie Campbell May 2nd, 2015

   Thank you so much! I’ve been struggling today trying to figure out how to display a custom image size with a full-size lightbox, and this helped immensely.