Why is IconButton a stateless widget in Flutter, rather than being a stateful widget?

Question

In the flutter documentation, it states

"A stateless widget never changes. Icon, IconButton, and Text are examples of stateless widgets. Stateless widgets subclass StatelessWidget.

A stateful widget is dynamic: for example, it can change its appearance in response to events triggered by user interactions or when it receives data. Checkbox, Radio, Slider, InkWell, Form, and TextField are examples of stateful widgets. Stateful widgets subclass StatefulWidget."

This is confusing to me, because an IconButton can change its appearance in response to events triggered by user interactions. I am not understanding the distinction between stateless and stateful given this example

when making a custom widget, I am unsure when to make it stateful or stateless

Answer 1

IconButton might be stateless but it uses widgets that are stateful (ButtonStyleButton in this case). The state is held by ButtonStyleButton and IconButton is only a wrapper around it to make it easier to use, set default values or use the correct theme.

when making a custom widget, I am unsure when to make it stateful or stateless

Always go for a StatelessWidget if you can. You only need StatefulWidget if you need to save something in the state (and use setState) or any other method of the StatefulWidget like initState for example. You could use initState to trigger an http call to an API only once when the widget is mounted for example.