# Image Button (lv_imagebutton) (/widgets/imagebutton)



Overview [#overview]

The Image Button is very similar to the simple 'Button' Widget. The only
difference is that it displays user-defined images for each state instead
of drawing a rectangle.  The list of states is covered below.

You can set a left, right and middle image, and the middle image will be
repeated to match the width of the Widget.

Parts and Styles [#parts-and-styles]

* <ApiLink name="LV_PART_MAIN" /> Refers to the image(s). If background style
  properties are used, a rectangle will be drawn behind the Image
  Button.

Usage [#usage]

Image sources [#image-sources]

To set the image in a state, use the
<ApiLink name="lv_imagebutton_set_src" display="lv_imagebutton_set_src(imagebutton, LV_IMAGEBUTTON_STATE_..., src_left, src_mid, src_right)" />.

The image sources work the same as described in the [Image Widget](/widgets/image)
except that "Symbols" are not supported by the Image Button. Any of the sources can be `NULL`.
Typically the middle image should be one of the set image sources.

If only `src_mid` is specified, the width of the widget will be set automatically to the
width of the image. However, if all three sources are set, the width needs to be set by the user
(using e.g. <ApiLink name="lv_obj_set_width" />) and the middle image will be tiled to fill the given size.

The possible states are:

* <ApiLink name="LV_IMAGEBUTTON_STATE_RELEASED" />
* <ApiLink name="LV_IMAGEBUTTON_STATE_PRESSED" />
* <ApiLink name="LV_IMAGEBUTTON_STATE_DISABLED" />
* <ApiLink name="LV_IMAGEBUTTON_STATE_CHECKED_RELEASED" />
* <ApiLink name="LV_IMAGEBUTTON_STATE_CHECKED_PRESSED" />
* <ApiLink name="LV_IMAGEBUTTON_STATE_CHECKED_DISABLED" />

The image sources set for state <ApiLink name="LV_IMAGEBUTTON_STATE_RELEASED" /> are
used for any state that has not had image sources set for it.  If an image sources
have been set for other states, e.g. <ApiLink name="LV_IMAGEBUTTON_STATE_PRESSED" />,
they will be used instead when the Image Button is in that state.

Setting State Programmatically [#setting-state-programmatically]

Instead of the regular <ApiLink name="lv_obj_add_state" /> and <ApiLink name="lv_obj_remove_state" /> functions,
use <ApiLink name="lv_imagebutton_set_state" display="lv_imagebutton_set_state(imagebutton, LV_IMAGEBUTTON_STATE_...)" /> to
set the state of Image Buttons.

Events [#events]

* <ApiLink name="LV_EVENT_VALUE_CHANGED" /> Sent when Image Button's CHECKED state is toggled.
  This requires the Image Button's <ApiLink name="LV_OBJ_FLAG_CHECKABLE" /> flag to be set.

<Callout type="info" title="Further Reading">
  Learn more about [Events](/common-widget-features/events) emitted by all Widgets.

  Learn more about [events](/common-widget-features/events).
</Callout>

Keys [#keys]

* `LV_KEY_RIGHT/UP` Go to CHECKED state if <ApiLink name="LV_OBJ_FLAG_CHECKABLE" />
  is enabled.
* `LV_KEY_LEFT/DOWN` Go to un-CHECKED state if
  <ApiLink name="LV_OBJ_FLAG_CHECKABLE" /> is enabled.
* <ApiLink name="LV_KEY_ENTER" /> Clicks the Image Button

<Callout type="info" title="Further Reading">
  Learn more about [Keys](/main-modules/indev/keypad).
</Callout>

Example [#example]

Simple Image button [#simple-image-button]

<LvglExample name="lv_example_imagebutton_1" path="widgets/imagebutton/lv_example_imagebutton_1" />

API [#api]