diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index 11c5cfb91..f2a83eca5 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -2706,13 +2706,17 @@ Some types may inherit styles from parent types.
     * alpha - boolean, whether to draw alpha in bgimg. Default true.
     * bgcolor - color, sets button tint.
     * bgcolor_hovered - color when hovered. Defaults to a lighter bgcolor when not provided.
+        * This is deprecated, use states instead.
     * bgcolor_pressed - color when pressed. Defaults to a darker bgcolor when not provided.
+        * This is deprecated, use states instead.
     * bgimg - standard background image. Defaults to none.
     * bgimg_hovered - background image when hovered. Defaults to bgimg when not provided.
+        * This is deprecated, use states instead.
     * bgimg_middle - Makes the bgimg textures render in 9-sliced mode and defines the middle rect.
                      See background9[] documentation for more details. This property also pads the
                      button's content when set.
     * bgimg_pressed - background image when pressed. Defaults to bgimg when not provided.
+        * This is deprecated, use states instead.
     * border - boolean, draw border. Set to false to hide the bevelled button pane. Default true.
     * content_offset - 2d vector, shifts the position of the button's content without resizing it.
     * noclip - boolean, set to true to allow the element to exceed formspec bounds.
@@ -2741,7 +2745,9 @@ Some types may inherit styles from parent types.
 * image_button (additional properties)
     * fgimg - standard image. Defaults to none.
     * fgimg_hovered - image when hovered. Defaults to fgimg when not provided.
+        * This is deprecated, use states instead.
     * fgimg_pressed - image when pressed. Defaults to fgimg when not provided.
+        * This is deprecated, use states instead.
     * NOTE: The parameters of any given image_button will take precedence over fgimg/fgimg_pressed
 * tabheader
     * noclip - boolean, set to true to allow the element to exceed formspec bounds.