Layouts

Layouts are the container widgets that arrange their children: BoxLayout in a row or column, GridLayout in a grid, FloatLayout with free placement, StackLayout that wraps, and the scrollable wrappers that make the list work. Every layout is a widget with a children list, and every child has a size_hint that tells the layout how to divide the space - the layout's entire job is to read those hints and assign positions and sizes. Mastering the four main layouts plus the scroll wrappers is mastering Kivy UI construction, because every screen is a tree of them.

BoxLayout: The Workhorse

BoxLayout:
    orientation: "vertical"      # "vertical" or "horizontal"
    padding: 10
    spacing: 8

    Label:
        text: "Header"
        size_hint_y: None       # take only what I need
        height: 40

    TextInput:
        hint_text: "Search"
        size_hint_y: None
        height: 50

    Button:
        text: "Go"
        size_hint_y: 1          # take ALL remaining space

BoxLayout stacks children in one direction (orientation). The division rule: a child with size_hint 1 along the axis takes a proportional share of the remaining space; a child with size_hint 0 along the axis (written size_hint_y: None) keeps its explicit height/width. The canonical header form is exactly the block above - fixed-height header and input, and the main content with size_hint: 1 absorbing the rest. padding insets the whole box, spacing is the gap between children. BoxLayout is where 80% of a Kivy UI lives, and the size_hint None-vs-1 choice is the decision that makes or breaks each screen.

GridLayout and StackLayout

GridLayout:
    columns: 3
    spacing: 6
    padding: 6

    Button: text: "1"
    Button: text: "2"
    Button: text: "3"
    Button: text: "4"
    Button: text: "5"
    Button: text: "6"

# StackLayout: like a box, but wraps to a new row/column when full
StackLayout:
    orientation: "ltr"
    spacing: 6
    Button: text: "tag"
    Button: text: "tag"
    Button: text: "tag"
    Button: text: "tag"
    Button: text: "tag"

GridLayout fills columns (or rows) left-to-right, top-to-bottom - the calculator and icon-grid shape; children get equal cells by default, or their own size_hint share. StackLayout is the wrapping box: it places children in order and starts a new row (or column) when the current one fills - the tag-chip and flow-layout use case. Both are widgets with the same children/size_hint contract as BoxLayout; the difference is purely the placement algorithm. For a grid of recipe cards, a GridLayout inside a ScrollView is the standard structure.

FloatLayout: Free Placement

FloatLayout:
    Image:
        source: "data/background.png"
        size_hint: (1, 1)
        pos_hint: {'center': (0.5, 0.5)}
    Label:
        text: "Overlay"
        size_hint: (0.3, 0.1)
        # anchor to the top-left with an offset
        pos_hint: {'top_left': (0.05, -0.05)}
    Button:
        text: "OK"
        size_hint: (0.2, 0.1)
        pos_hint: {'center': (0.5, 0.1)}

FloatLayout does not stack - it places each child by pos_hint, a dict mapping an anchor (center, top_left, right, the nine anchor points plus center) to an (x, y) offset as a fraction of the parent. It is the layout for overlays, full-bleed backgrounds, and anything positioned relative to the screen rather than in a flow. The cost is that it does not respond to content - a FloatLayout full of labels does not reflow when the text changes - so it is for deliberate placement, not for a list of items. The background-plus-overlay pattern (an Image at (1,1) with a Label and a Button positioned over it) is its most common job.

ScrollView and the List

ScrollView:
    bar_width: 8
    do_scroll_x: False
    do_scroll_y: True

    BoxLayout:
        orientation: "vertical"
        size_hint_y: None
        height: self.minimum_height

        Label: text: "Recipe 1"
        Label: text: "Recipe 2"
        Label: text: "Recipe 3"
        Label: text: "Recipe 4"

The ScrollView is the wrapper that makes any layout scrollable, and it has one hard requirement: its single child must have a size_hint of 0 along the scroll axis and an explicit size (here size_hint_y: None plus height: self.minimum_height, where minimum_height is the height the content actually needs). Without that, the child fills the viewport and there is nothing to scroll. do_scroll_x/do_scroll_y gate the directions, bar_width sizes the scrollbar. The recipe list - a ScrollView around a vertical BoxLayout of item widgets - is the pattern for every list UI, and the data-driven chapter shows how to populate it from data instead of hard-coding the labels.

Choosing the Layout

The decision is the shape of the content: flow in one direction is a Box, a matrix is a Grid, wrapping is a Stack, deliberate placement is a Float, and any of them that can grow past the viewport gets a ScrollView. The compositions are what real screens are - a vertical Box whose first child is a header, whose second is a ScrollView wrapping a Grid of cards. The discipline: the layout tree mirrors the visual structure, one level of nesting per visual grouping, and the size_hint at each level is the contract that makes the division work.

Summary

The four main layouts, each a widget whose children are placed by their size_hint: BoxLayout (one direction, the workhorse - fixed children with size_hint: None and explicit dimensions, flexible children with 1), GridLayout (a matrix), StackLayout (wrapping flow), and FloatLayout (free placement by pos_hint anchors). The ScrollView wraps any of them for scrolling, with the non-negotiable rule that its child has size_hint: None along the scroll axis and an explicit minimum_ size. Real screens are compositions - a Box containing a header and a ScrollView containing a Grid - and the choice table is the decision: match the layout to the content shape, one nesting level per visual group, and let the size hints do the division.