Core Widgets

The core widgets are the vocabulary of every Kivy UI: Label shows text, Button takes a press, Image shows a picture, TextInput and TextField take input, Slider and Switch take a value, and the containers (covered next) arrange them. All of them are Widget subclasses with the same shape - a size, a position, a canvas, and a set of properties that define their appearance and state. This chapter covers the display widgets, the input widgets, and the properties that matter for each, with the running recipe-manager UI as the context.

Display: Label, Image, and Their Properties

BoxLayout:
    orientation: "vertical"
    Label:
        text: "Recipe: Tomato Soup"
        font_size: 28
        bold: True
        # text is multi-line by default; halign/valign position it
        halign: "center"
        valign: "middle"
    Image:
        source: "data/soup.png"
        # allow the image to scale within its allocated space
        allow_stretch: True
        keep_ratio: True
        size_hint: (1, 0.6)

Label renders text: text (multi-line, supports a subset of markup), font_size, bold/italic, and the alignment properties. A label that is too small for its text does not scroll or clip by default - it overflows - so size it with size_hint or give it a fixed height, and use markup for inline formatting when needed. Image shows a source (a path, a URL, or a BytesIO): allow_stretch lets it scale to the allocated space, keep_ratio preserves aspect ratio, and size_hint controls how much space it takes. The two properties that make images behave in a layout are allow_stretch plus keep_ratio - without stretch, an image keeps its pixel size regardless of the layout, which is the "why is my image the wrong size" cause in most Kivy UIs.

Button and the Press Event

BoxLayout:
    orientation: "horizontal"
    Button:
        text: "Save"
        background_color: (0.2, 0.5, 0.3, 1)
        on_press: root.save_recipe()
    Button:
        text: "Delete"
        # a button can be disabled - it ignores presses and dims
        disabled: True

Button is the primary action widget: text labels it, background_color (a 4-tuple RGBA) styles it, and on_press is the event that fires on tap. disabled is the standard way to gate an action (the Delete button stays inert until a recipe is selected) - a disabled button neither fires its event nor accepts touches. Buttons are also the carrier for icon-plus-label patterns via a small custom widget (the custom-widgets chapter), and the on_release variant fires when the touch lifts, which is the right event when the action should commit only on a full tap rather than on press-down.

Input: TextInput, TextField, Slider, Switch

BoxLayout:
    orientation: "vertical"
    TextField:
        id: name_field
        hint_text: "Recipe name"
        input_filter: "ascii"
        on_text_validate: root.commit_name(self.text)
    TextInput:
        id: notes
        hint_text: "Notes (multi-line)"
        multiline: True
        size_hint_y: 0.4
    Slider:
        id: servings
        value: 2
        min_value: 1
        max_value: 12
        step: 1
        tick_spacing: 1
    Switch:
        id: favorite
        active: False

The input widgets cover the standard controls. TextField is the single-line text input with hint_text (the placeholder), input_filter (restrict to ascii, int, float, or a callable), and on_text_validate (fires on the Enter key - the "submit" event for a field). TextInput is its multi-line sibling (multiline: True), the notes box. Slider takes a continuous or stepped value - min_value/max_value/step, with tick_spacing drawing the tick marks - and its value property is what you read or bind. Switch is the boolean toggle, active on/off. The pattern for all of them: read the property (value, text, active) in the handler, or bind it to a property that drives the rest of the UI (the properties chapter). The recipe form is the standing example: a name field, a notes input, a servings slider, a favorite switch - the four input types in one screen.

Widget State: The Properties That Matter

Every widget shares a core set of state properties, and the two that govern layout are size_hint (the fraction of the parent's space the widget wants, as an (x, y) pair) and pos_hint (the anchor for absolute-ish placement in a FloatLayout). size_hint is the single most important property in a Kivy UI - it is how a widget says "give me half the height" (size_hint_y: 0.5) or "take all the width" (size_hint_x: 1) - and the layouts chapter is about how the containers honor those hints. disabled, opacity, and the color properties are the styling and state layer that makes a UI readable: the disabled Delete button, the dimmed inactive tab, the colored Save. Learn the table and the two layout properties, and the core widgets stop being a list of classes and become a toolkit you compose.

Summary

The core widgets are the UI vocabulary: Label and Image for display (with allow_stretch/keep_ratio making images behave in a layout), Button for actions (on_press, disabled), and the input family - TextField (single-line, on_text_validate for submit), TextInput (multi-line), Slider (value with min/max/step), Switch (active). The shared state properties - disabled, opacity, the color tuples - are the styling layer, and size_hint is the property that matters most, because it is how a widget asks its layout for space. The recipe form (name field, notes, servings slider, favorite switch) is the standing example, and the next chapter is the layouts that give those widgets their positions.