Icon Names

GTK 2 had stock items: gtk.STOCK_SAVE was an icon, a translated label and a keyboard accelerator in one constant. The whole system was deprecated in GTK 3.10 and removed in GTK 4. What replaced it is simpler and less helpful: an icon is a name, looked up in the icon theme, and the label and the accelerator are your problem.

Gtk.Button(icon_name="document-save-symbolic")
Gtk.Image.new_from_icon_name("dialog-warning-symbolic")
notification.set_icon(Gio.ThemedIcon.new("document-save-symbolic"))

The names come from the freedesktop icon naming specification, which every icon theme implements, so an icon named this way changes with the user’s theme instead of being baked into your application.

The -symbolic suffix

Nearly every name below has a -symbolic variant, and in a GTK 4 application that is almost always the one you want. Symbolic icons are single-colour and are recoloured by GTK to match the text around them, so they stay legible in a dark theme, in a selected row, and on a coloured button. The full-colour variant (the same name without the suffix) is for large presentations of a thing — an application icon, a file type in a grid.

Checking a name exists

An icon name that the theme does not have renders as the “missing image” icon rather than raising, so a typo is silent. To check:

theme = Gtk.IconTheme.get_for_display(Gdk.Display.get_default())
print(theme.has_icon("document-save-symbolic"))

The gtk4-icon-browser tool, part of the GTK development packages, lists everything the theme has with a searchable index. It is the fastest way to find a name, and worth having open while you write.

Every name in this appendix was checked against the Adwaita theme shipped with GTK 4.22.

Files and documents

Editing

Text formatting

Navigation

The go-previous and go-next icons mirror themselves in a right-to-left locale, which is why you should use them rather than go-left/go-right. Several names also have an explicit -rtl variant for cases where GTK cannot work out the correct direction on its own.

View and zoom

Media

media-playback-start-symbolic mirrors in a right-to-left locale; the skip and seek icons do too.

Dialogs and status

Names with no stock ancestor

Worth knowing, because they are everywhere in modern applications:

open-menu-symbolic

The hamburger button on a header bar.

view-more-symbolic

A secondary menu, usually on a row rather than the header bar.

object-select-symbolic

A tick. This is the “OK” icon — there is no emblem-ok.

content-loading-symbolic

Something is in progress.

tab-new-symbolic, send-to-symbolic, starred-symbolic, non-starred-symbolic,

find-location-symbolic, selection-mode-symbolic

The rest of the common vocabulary.

Stock items with no replacement

Some GTK 2 stock items have no icon equivalent, and that is deliberate rather than an oversight:

STOCK_OK, STOCK_CANCEL, STOCK_YES, STOCK_NO, STOCK_APPLY, STOCK_CLOSE

(as a dialog button)

Use a labelled button. The guidance now is that a dialog’s buttons should say what they do — “Delete”, “Replace”, “Discard” — rather than “OK”, and an icon on a dialog button is noise. Gtk.AlertDialog.set_buttons(["Cancel", "Delete"]) takes plain strings for exactly this reason.

STOCK_CONNECT, STOCK_DISCONNECT, STOCK_CONVERT, STOCK_INDEX,

STOCK_ORIENTATION_*, STOCK_PAGE_SETUP, STOCK_DND

Too application-specific to be in a shared theme. Ship your own icon in your application’s GResource and name it after your application id, or find a closer generic name in gtk4-icon-browser.

The label and accelerator halves of a stock item are gone too. Where GTK 2 gave you a translated “_Save” and Ctrl+S for free, you now write them yourself:

file_menu.append(_("_Save"), "app.save")
app.set_accels_for_action("app.save", ["<Control>s"])

See Menus and actions for the whole pattern, and Internationalization for translating the labels.