Skip to main content
`Ctrl`+`K`

# Label

Labels are the main method of placing non-editable text in windows, for instance to place a title next to a `Gtk.Entry` widget. You can specify the text in the constructor, or later with the `Gtk.Label.props.label` property.

The width of the label will be adjusted automatically. You can produce multi-line labels by putting line breaks (`\n`) in the label string.

Labels can be made selectable with `Gtk.Label.props.selectable`. Selectable labels allow the user to copy the label contents to the clipboard. Only labels that contain useful-to-copy information — such as error messages — should be made selectable.

The label text can be justified using the `Gtk.Label.props.justify` prop. The widget is also capable of word-wrapping, which can be activated with `Gtk.Label.props.wrap`. You can configure this wrapping by changing `Gtk.Label.props.wrap_mode`, in can be `Pango.WrapMode.WORD`, `Pango.WrapMode.CHAR` or `Pango.WrapMode.WORD_CHAR`.

`Gtk.Label` support some simple formatting, for instance allowing you to make some text bold, colored, or larger. You can do this by enabling markup setting `Gtk.Label.props.use_markup` to `True`, then you can use markup with `Gtk.Label.props.label` using the Pango Markup syntax [1]. For instance, `<b>bold text</b> and <s>strikethrough text</s>`. In addition, `Gtk.Label` supports clickable hyperlinks. The markup for links is borrowed from HTML, using the a with href and title attributes. GTK renders links similar to the way they appear in web browsers, with colored, underlined text. The title attribute is displayed as a tooltip on the link. `Gtk.Label.set_markup()` method can be used to set the text and enable markup at the same time.

    label.set_markup("Go to <a href=\"https://www.gtk.org\" "
                     "title=\"Our website\">GTK+ website</a> for more")

Labels may contain mnemonics. Mnemonics are underlined characters in the label, used for keyboard navigation. Mnemonics are created by providing a string with an underscore before the mnemonic character, such as “_File”, to the functions `Gtk.Label.new_with_mnemonic()` or `Gtk.Label.set_text_with_mnemonic()`. Mnemonics automatically activate any activatable widget the label is inside, such as a `Gtk.Button`; if the label is not inside the mnemonic’s target widget, you have to tell the label about the target using `Gtk.Label.props.mnemonic_widget`.

You can also change the alignment of the label text inside its size allocation. For example if you use `Gtk.Widget.props.hexpand` in a label, the label may take more space than its inner text. You can change this alignment using `Gtk.Label.props.xalign` for horizontal alignment and `Gtk.Label.props.yalign` for vertical.

## Example

      1import gi
      2
      3gi.require_version("Gtk", "4.0")
      4from gi.repository import Gtk
      5
      6
      7class LabelWindow(Gtk.ApplicationWindow):
      8    def __init__(self, **kargs):
      9        super().__init__(**kargs, title="Label Demo")
     10
     11        box = Gtk.Box(spacing=10)
     12        self.set_child(box)
     13
     14        box_left = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=10)
     15        box_left.props.hexpand = True
     16        box_left.props.homogeneous = True
     17        box_right = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=10)
     18
     19        box.append(box_left)
     20        box.append(box_right)
     21
     22        label = Gtk.Label(label="This is a normal label")
     23        box_left.append(label)
     24
     25        label = Gtk.Label(label="This is a normal label with xalign set to 0")
     26        label.props.xalign = 0
     27        box_left.append(label)
     28
     29        label = Gtk.Label()
     30        label.props.label = "This is a left-justified label.\nWith multiple lines."
     31        label.props.justify = Gtk.Justification.LEFT
     32        box_left.append(label)
     33
     34        label = Gtk.Label(
     35            label="This is a right-justified label.\nWith multiple lines."
     36        )
     37        label.props.justify = Gtk.Justification.RIGHT
     38        box_left.append(label)
     39
     40        label = Gtk.Label(
     41            label="This is an example of a line-wrapped label.  It "
     42            "should not be taking up the entire             "
     43            "width allocated to it, but automatically "
     44            "wraps the words to fit.\n"
     45            "     It supports multiple paragraphs correctly, "
     46            "and  correctly   adds "
     47            "many          extra  spaces. "
     48        )
     49        label.props.wrap = True
     50        label.props.max_width_chars = 32
     51        box_right.append(label)
     52
     53        label = Gtk.Label(
     54            label="This is an example of a line-wrapped, filled label. "
     55            "It should be taking "
     56            "up the entire              width allocated to it.  "
     57            "Here is a sentence to prove "
     58            "my point.  Here is another sentence. "
     59            "Here comes the sun, do de do de do.\n"
     60            "    This is a new paragraph.\n"
     61            "    This is another newer, longer, better "
     62            "paragraph.  It is coming to an end, "
     63            "unfortunately."
     64        )
     65        label.props.wrap = True
     66        label.props.justify = Gtk.Justification.FILL
     67        label.props.max_width_chars = 32
     68        box_right.append(label)
     69
     70        label = Gtk.Label()
     71        label.set_markup(
     72            "Text can be <small>small</small>, <big>big</big>, "
     73            "<b>bold</b>, <i>italic</i> and even point to "
     74            'somewhere in the <a href="https://www.gtk.org" '
     75            'title="Click to find out more">internets</a>.'
     76        )
     77        label.props.wrap = True
     78        label.props.max_width_chars = 48
     79        box_left.append(label)
     80
     81        label = Gtk.Label.new_with_mnemonic(
     82            "_Press Alt + P to select button to the right"
     83        )
     84        box_left.append(label)
     85        label.props.selectable = True
     86
     87        button = Gtk.Button(label="Click at your own risk")
     88        label.props.mnemonic_widget = button
     89        box_right.append(button)
     90
     91
     92def on_activate(app):
     93    win = LabelWindow(application=app)
     94    win.present()
     95
     96
     97app = Gtk.Application(application_id="com.example.App")
     98app.connect("activate", on_activate)
     99
    100app.run(None)

[1]

Pango Markup Syntax, https://docs.gtk.org/Pango/pango_markup.html