4.6.x theme.inc theme_image($path, $alt = '', $title = '', $attr = '', $getsize = true)
4.7.x theme.inc theme_image($path, $alt = '', $title = '', $attributes = NULL, $getsize = TRUE)
5.x theme.inc theme_image($path, $alt = '', $title = '', $attributes = NULL, $getsize = TRUE)
6.x theme.inc theme_image($path, $alt = '', $title = '', $attributes = NULL, $getsize = TRUE)
7.x theme.inc theme_image($variables)

Returns HTML for an image.


$variables: An associative array containing:

  • path: Either the path of the image file (relative to base_path()) or a full URL.
  • width: The width of the image (if known).
  • height: The height of the image (if known).
  • alt: The alternative text for text-based browsers. HTML 4 and XHTML 1.0 always require an alt attribute. The HTML 5 draft allows the alt attribute to be omitted in some cases. Therefore, this variable defaults to an empty string, but can be set to NULL for the attribute to be omitted. Usually, neither omission nor an empty string satisfies accessibility requirements, so it is strongly encouraged for code calling theme('image') to pass a meaningful value for this variable.

  • title: The title text is displayed when the image is hovered in some popular browsers.
  • attributes: Associative array of attributes to be placed in the img tag.

Related topics

17 theme calls to theme_image()
ImageFieldDisplayTestCase::testImageFieldDefaultImage in modules/image/image.test
Test use of a default image with an image field.
ImageFieldDisplayTestCase::testImageFieldSettings in modules/image/image.test
Tests for image field settings.
ImageFieldDisplayTestCase::_testImageFieldFormatters in modules/image/image.test
Test image formatters on node display.
seven_tablesort_indicator in themes/seven/template.php
Override of theme_tablesort_indicator().
simpletest_result_status_image in modules/simpletest/simpletest.pages.inc
Get the appropriate image for the status.

... See full list


includes/theme.inc, line 1877
The theme system, which controls the output of Drupal.


function theme_image($variables) {
  $attributes = $variables['attributes'];
  $attributes['src'] = file_create_url($variables['path']);

  foreach (array('width', 'height', 'alt', 'title') as $key) {

    if (isset($variables[$key])) {
      $attributes[$key] = $variables[$key];

  return '<img' . drupal_attributes($attributes) . ' />';


sylv3st3r’s picture

derjochenmeyer’s picture

  $variables = array(
      'path' => 'path/to/img.jpg', 
      'alt' => 'Test alt',
      'title' => 'Test title',
      'width' => '50%',
      'height' => '50%',
      'attributes' => array('class' => 'some-img', 'id' => 'my-img'),
  $img = theme('image', $variables);
Bagz’s picture

This example seems to be misaligned with the topic. The topic is about the theme_image($variables) function, but the example does not show this.
The example shows the theme() function which is a different function.
Staying on topic, the example should show as the last line $img = theme_image($variables);

johnvsc’s picture

This always trips up n00bies.

dazweeja’s picture

The example is correct as it allows this theme function to be overridden in a template or module. Calling theme_image directly does not and so is not recommended.

daggar’s picture

There are several good reasons to use theme() instead of theme_image(), but that's a different discussion. Here's a correct example of theme_image for drupal 7:

$arbitrary_array = array(
  'path' => '/sites/all/arbitrary_theme/images/image.jpg',
  'alt' => 'Alternate Text',
  'title' => 'Image Title',
  'width' => '100px',
  'height' => '50px',
  'attributes' => array('class' => 'some-img', 'id' => 'my-img'),
print theme_image($arbitrary_array);

Note that I used the 'print' command. theme_image, on its own, only produces code without outputting it.

blainelang’s picture

D7: There's lots of cross linking to other issues but I still don't really understand why all the options now have to be specified when you call theme_image() and I can't just pass in array('path' => $mypath')

Why does theme_image not default the parameters like most other theme functions?

blainelang’s picture

So re-reading the notes on issue: http://drupal.org/node/1004556 and I see that it's recommended that we use theme('image', array('path' => $mypath)); instead of theme_image();

Can do as in my case, allows me to not pass in the other parameters and now I don't get the PHP notice messages.

daggar’s picture

Drupal 7's API is more of a PI-- that is, not very advanced. For any image in the system, all the relevant information is stored in existing structures, but the API does not access any of it, and requires the coder to supply the most basic information. D7 seems to be falling victim to abstraction fetishism at the cost of everyday usability.

avukonke’s picture

I share the same sentiment, the way that images are used and manipulated in the Drupal way is so counter-productive. Spent an hour trying to insert a simple image, just because there is no specificity with regards to image manipulation. PHP and Drupal. Python is the future. I would have this done in 5min and 5 lines

scotself’s picture

in case any themers end up here as I did, in D7, it's as simple as <?php print render($content['field_mypic']); ?> to stick a fully rendered version of your image field in your tpl files.

meustrus’s picture

The documentation for the 'path' variable seems inconsistent with actual usage. Should 'path' be a URI and not "Either the path of the image file (relative to base_path()) or a full URL"? For that matter, if it's going to be used that way, shouldn't it be called 'uri' instead of 'path'?

avukonke’s picture

For anyone that has experienced a similar problem and has need to hard code the image (via the tag) then these are a couple of lines that could come in handy:

Firstly ensure that in your view you specify;

Formatter (Image URL)
Image Style (None)
Link Image URL (Nothing)

Under Style Settings select "Customize field HTML" and then under
HTML ELEMENT(nothing), this is done because for some unknown reason Drupal inserts opening and closing tags to the image.

The Syntax is as follows :

    $image_url = $fields['field_speaker_image']->content;
    $speaker_image_url = "'$image_url'";
    $image_alt = $fields['field_speaker_name']->content;
    $speaker_image_alt = "'$image_alt'";
    $image_title = $fields['field_speaker_title']->content;
    $speaker_image_title = "'$image_title'";

The image_url is the image path retrieved from the view. The image alt and image_title are optional extras, that you can add in as you please.

Then finally here is the image tag that you can manipulate as you wish:

<img src= <?php print $speaker_image_url; ?>  alt= <?php print $speaker_image_alt; ?> title= <?php print $speaker_image_title; ?> width="50" height="70" style="some_style"/>

Enjoy !!!

zterry95’s picture

another tips for using this api.
For example, if you want to add border to image, coding like below.

$image = theme('image_style',array(
    'style_name' => 'mail_image_big',
    'path' => $image_obj['uri'],
    'attributes' => array('style' => 'border:1px solid #aaa;')
panditvarun20’s picture

For video render using theme function which process is used

alala0000’s picture

Just a reminder that you must include the 'attributes' key in the array, even if you have no extra attributes needed to add. Otherwise it will throw error on the 'attributes' key can not be found.
(Although error reporting should have been turned off in production site anyway.)
i.e. theme_image( array( 'path' => 'some_path', 'attributes' => array() );

abbym’s picture

I realize that this is the Drupal 7 page, but felt that it was worth mentioning explicitly that this function appears to be deprecated in Drupal 8, since there are several places around the web that indicate otherwise. It will render a lovely WSOD for your viewing pleasure.