Skip to content

Image Widget

The image widget is used to display an image on a slide. It's also used to display animated images, which can either be animated GIFs or a folder or zip file of sequentially-numbered images (of any type).

Image types that support alpha channels (like PNGs) are supported.



Image widgets also have "common" widget settings for position, opacity, animations, color, style, etc. Those are not listed here, but are instead covered in common widget settings page.

Also remember that all widget settings can be controlled via widget styles, rather than you having to set every setting on every widget.

The following image widget settings may be animated: x:, y:, color:, rotation:, scale:, fps:, current_frame:, and opacity:.

type: image

Single value, type: string.

Tells MPF that this is an image widget


Single value, type: string name of a image.

The name of the image asset this widget will show. Details on image assets are here.


Single value, type: integer. Default: 10.

For animated images, sets how fast it plays (frames per second).


Single value, type: integer. Default: -1.

The number of times an animated image will loop. Set to -1 for unlimited. Note this is now consistent in 0.50 with other areas of MPF. In earlier versions of MPF this setting used 0 to specify unlimited loops.


Single value, type: boolean (Yes/No or True/False). Default: True

If the image is an animated image, configures whether it plays automatically when it's loaded.

This is good for looping images, but if you have an image you want to play at a specific point, you probably want to set this to no and play it from specific events via the widget player.


Single value, type: integer. Default: 0.

Which start frame to use for animated images.


Single value, type: boolean (true/false). Default: false

When true, the animated image widget will remember the frame the it was on when it was last used, and restore that frame when the widget is next used.

By default, an animated image will reset itself each time it is added to a slide.

Something missing or wrong? You can fix it!

This website is edited by people like you! Is something wrong or missing? Is something out of date, or can you explain it better?

Please help us! You can fix it yourself and be an official "open source" contributor!

It's easy! See our Beginner's guide to editing the docs.

Page navigation via the keyboard: < >

You can navigate this site via the keyboard. There are two modes:

General navigation, when search is not focused:

  • F , S , / : open search dialog
  • P , , : go to previous page
  • N , . : go to next page

While using the search function:

  • Down , Up : select next / previous result
  • Esc , Tab : close search
  • Enter : go to highlighted page in the results