Row

A layout builder that arranges its children horizontally.

A Row places its children one after another in a left-to-right sequence. It's a fundamental container for creating side-by-side layouts.

Example

from pictex import Row, Image, Text

# Create a user banner with an avatar and text aligned vertically.
user_banner = Row(
    Image("avatar.jpg").size(60, 60).border_radius('50%'),
    Text("Username").font_size(24)
).gap(15).align_items('center')

size(width=None, height=None)

Sets the explicit size of the element's box using the border-box model.

The width and height are defined independently and control the total dimensions of the element, including its padding and border.

Each dimension supports several modes:

• 'auto': The size is context-dependent. It typically behaves like 'fit-content', but will yield to parent layout constraints, such as stretching to fill the space in a Row or Column with align stretch. This is the default behavior.

• 'fit-content': The size is explicitly set to wrap the element's content. This will override parent constraints like stretch.

• 'fit-background-image': The size is explicitly set to match the dimensions of the element's background image.

• Absolute (pixels): An int or float value (e.g., 200) sets a fixed size.

• Percentage: A str ending with % (e.g., "50%") sets the size relative to the parent container's content area.

Note: To make an element flexible and fill available space, use .flex_grow(1) instead of setting a size mode.

Parameters:

Name	Type	Description	Default
width	Union[float, int, str]	The horizontal size value. Defaults to "auto".	None
height	Union[float, int, str]	The vertical size value. Defaults to "auto".	None

Returns:

Name	Type	Description
Self	Self	The instance for method chaining.

width(value)

Sets the explicit width of the element's box.

This is a convenience method that is equivalent to calling size(width=value).

Parameters:

Name	Type	Description	Default
value	SizeInput	The horizontal size value. See size() for supported formats.	required

Returns:

Name	Type	Description
Self	Self	The instance for method chaining.

height(value)

Sets the explicit height of the element's box.

This is a convenience method that is equivalent to calling size(height=value).

Parameters:

Name	Type	Description	Default
value	SizeInput	The vertical size value. See size() for supported formats.	required

Returns:

Name	Type	Description
Self	Self	The instance for method chaining.

fit_background_image()

Adjusts the element's size to match its background image dimensions.

This is a convenience method that sets the element's width and height to fit the natural size of the background image. It is a shortcut for calling size(width='fit-background-image', height='fit-background-image').

This is particularly useful for ensuring an element, like a Row or Column, perfectly contains its background image without distortion or cropping, allowing other content to be layered on top.

The behavior can be overridden by a subsequent call to .size().

Example

# A Row that automatically sizes itself to the 'background.png'
# before rendering text on top of it.
Row()
    .background_image("path/to/background.png")
    .fit_background_image()
    .render(Text("Text over the full image").position("center", "center"))

Returns:

Name	Type	Description
Self	Self	The instance for method chaining.

min_width(value)

Sets the minimum width constraint for the element.

Ensures the element never shrinks below this width, regardless of content or flex shrinking behavior.

Parameters:

Name	Type	Description	Default
value	Union[float, int, str]	Minimum width value. Can be: - Absolute (pixels): int or float (e.g., 100) - Percentage: str ending with '%' (e.g., "50%")	required

Returns:

Name	Type	Description
Self	Self	The instance for method chaining.

Example

# Ensure text never collapses below 100px
Text(username).flex_grow(1).min_width(100)

max_width(value)

Sets the maximum width constraint for the element.

Ensures the element never grows beyond this width, regardless of content or flex growing behavior.

Parameters:

Name	Type	Description	Default
value	Union[float, int, str]	Maximum width value. Can be: - Absolute (pixels): int or float (e.g., 300) - Percentage: str ending with '%' (e.g., "80%")	required

Returns:

Name	Type	Description
Self	Self	The instance for method chaining.

Example

# Prevent long names from breaking layout
Text(product_name).size(width="fit-content").max_width(200)

min_height(value)

Sets the minimum height constraint for the element.

Ensures the element never shrinks below this height, regardless of content or flex shrinking behavior.

Parameters:

Name	Type	Description	Default
value	Union[float, int, str]	Minimum height value. Can be: - Absolute (pixels): int or float (e.g., 50) - Percentage: str ending with '%' (e.g., "30%")	required

Returns:

Name	Type	Description
Self	Self	The instance for method chaining.

Example

# Ensure card has minimum height even with little content
Column(children).min_height(200)

max_height(value)

Sets the maximum height constraint for the element.

Ensures the element never grows beyond this height, regardless of content or flex growing behavior.

Parameters:

Name	Type	Description	Default
value	Union[float, int, str]	Maximum height value. Can be: - Absolute (pixels): int or float (e.g., 400) - Percentage: str ending with '%' (e.g., "90%")	required

Returns:

Name	Type	Description
Self	Self	The instance for method chaining.

Example

# Limit description height with overflow
Text(description).max_height(150)

aspect_ratio(ratio)

Sets the aspect ratio constraint for the element.

Maintains a specific width-to-height proportion. When one dimension is specified (e.g., width), the other is calculated automatically to maintain the ratio.

The aspect ratio is expressed as width/height. Common examples: - Square: 1.0 or 1 - Landscape 16:9: 16/9 ≈ 1.778 - Portrait 9:16: 9/16 ≈ 0.5625 - Golden ratio: 1.618

Parameters:

Name	Type	Description	Default
ratio	Union[float, int, str]	Width-to-height ratio. Can be: - Float or int: Direct ratio value (e.g., 1.5, 16/9) - String with division: "16/9", "4/3", "1/1"	required

Returns:

Name	Type	Description
Self	Self	The instance for method chaining.

Example

# 16:9 video placeholder - specify width, height auto-calculated
Element().size(width=400).aspect_ratio(16/9)  # height = 225

# Square Instagram post
Element().size(width=300).aspect_ratio(1)  # height = 300

# Vertical story format
Element().size(height=600).aspect_ratio(9/16)  # width = 337.5

absolute_position(*, top=None, right=None, bottom=None, left=None)

Position element absolutely (out of normal flow).

The element is positioned relative to its nearest ancestor.

Parameters:

Name	Type	Description	Default
top	InsetValue	Distance from top edge	None
right	InsetValue	Distance from right edge	None
bottom	InsetValue	Distance from bottom edge	None
left	InsetValue	Distance from left edge	None

Returns:

Name	Type	Description
Self	Self	The instance for method chaining.

Example

Text("Badge").absolute_position(top=10, right=10)
Text("Footer").absolute_position(bottom=0, left=0, right=0)

fixed_position(*, top=None, right=None, bottom=None, left=None)

Position element fixed (out of normal flow, relative to canvas).

The element is always positioned relative to the canvas (viewport), regardless of its position in the DOM tree. This is like CSS position: fixed.

Parameters:

Name	Type	Description	Default
top	InsetValue	Distance from canvas top edge	None
right	InsetValue	Distance from canvas right edge	None
bottom	InsetValue	Distance from canvas bottom edge	None
left	InsetValue	Distance from canvas left edge	None

Returns:

Name	Type	Description
Self	Self	The instance for method chaining.

Example

Text("Watermark").fixed_position(bottom=10, right=10)
Text("Header").fixed_position(top=0, left=0, right=0)

relative_position(*, top=None, right=None, bottom=None, left=None)

Position element relatively (stays in flow, but offset visually).

The element remains in normal flow but is visually offset by the specified values.

Parameters:

Name	Type	Description	Default
top	InsetValue	Offset from normal top position	None
right	InsetValue	Offset from normal right position	None
bottom	InsetValue	Offset from normal bottom position	None
left	InsetValue	Offset from normal left position	None

Returns:

Name	Type	Description
Self	Self	The instance for method chaining.

Example

Text("Nudged").relative_position(top=5, left=5)

translate(*, x=None, y=None)

Apply a translate transform to the element.

This is applied post-layout as a visual offset. Commonly used with absolute_position for true centering.

Values can be pixels (int/float) or percentages of the element's own size (str like "-50%").

Parameters:

Name	Type	Description	Default
x	TranslateValue	Horizontal translation	None
y	TranslateValue	Vertical translation	None

Returns:

Name	Type	Description
Self	Self	The instance for method chaining.

Example

# True centering
Text("Centered").absolute_position(top="50%", left="50%").translate(x="-50%", y="-50%")

place(horizontal, vertical, x_offset=0, y_offset=0)

Place element using anchor-based positioning (canvas-relative).

This is a convenience method that combines fixed positioning and translate to provide intuitive anchor-based placement relative to the canvas (viewport).

Parameters:

Name	Type	Description	Default
horizontal	Union[float, int, str]	Horizontal anchor - "left", "center", "right", pixels, or "X%"	required
vertical	Union[float, int, str]	Vertical anchor - "top", "center", "bottom", pixels, or "Y%"	required
x_offset	float	Additional horizontal offset in pixels (default 0)	0
y_offset	float	Additional vertical offset in pixels (default 0)	0

Returns:

Name	Type	Description
Self	Self	The instance for method chaining.

Example

Text("Overlay").place("center", "center")
Text("Badge").place("right", "top", x_offset=-10, y_offset=10)

font_family(family)

Sets the font family or a path to a font file.

Parameters:

Name	Type	Description	Default
family	Union[str, Path]	The name of the font family or a Path object to a font file.	required

Returns:

Type	Description
Self	The Self instance for chaining.

font_fallbacks(*fonts)

Specifies a list of fallback fonts.

These fonts are used for characters not supported by the primary font.

Parameters:

Name	Type	Description	Default
*fonts	Union[str, Path]	A sequence of font names or Path objects to font files.	()

Returns:

Type	Description
Self	The Self instance for chaining.

font_size(size)

Sets the font size in points.

Parameters:

Name	Type	Description	Default
size	float	The new font size.	required

Returns:

Type	Description
Self	The Self instance for chaining.

font_weight(weight)

Sets the font weight.

Parameters:

Name	Type	Description	Default
weight	Union[FontWeight, int, str]	The font weight, e.g., FontWeight.BOLD, 700 or "bold".	required

Returns:

Type	Description
Self	The Self instance for chaining.

font_style(style)

Sets the font style.

Parameters:

Name	Type	Description	Default
style	Union[FontStyle, str]	The font style, e.g., FontStyle.ITALIC.	required

Returns:

Type	Description
Self	The Self instance for chaining.

color(color)

Sets the text color or gradient.

Parameters:

Name	Type	Description	Default
color	Union[str, PaintSource]	A color string (e.g., "red", "#FF0000") or a PaintSource object.	required

Returns:

Type	Description
Self	The Self instance for chaining.

text_shadows(*shadows)

Sets the shadow effects for the text.

Parameters:

Name	Type	Description	Default
*shadows	Shadow	A sequence of one or more Shadow objects.	()

Returns:

Type	Description
Self	The Self instance for chaining.

text_stroke(width, color, mode='center')

Adds a stroke to the text.

Parameters:

Name	Type	Description	Default
width	float	The width of the stroke in pixels.	required
color	Union[str, PaintSource]	The color of the stroke.	required
mode	Union[str, StrokeMode]	The stroke rendering mode: "center", "outline", or "inline".	'center'

Returns:

Type	Description
Self	The Self instance for chaining.

underline(thickness=2.0, color=None)

Adds an underline text decoration.

Parameters:

Name	Type	Description	Default
thickness	float	The thickness of the underline.	2.0
color	Optional[Union[str, PaintSource]]	The color of the underline. If None, the main text color is used.	None

Returns:

Type	Description
Self	The Self instance for chaining.

strikethrough(thickness=2.0, color=None)

Adds a strikethrough text decoration.

Parameters:

Name	Type	Description	Default
thickness	float	The thickness of the strikethrough line.	2.0
color	Optional[Union[str, PaintSource]]	The color of the line. If None, the main text color is used.	None

Returns:

Type	Description
Self	The Self instance for chaining.

letter_spacing(value)

Sets the extra space between characters (CSS letter-spacing).

Parameters:

Name	Type	Description	Default
value	Union[float, int, str, LetterSpacing]	Absolute pixels (float/int), a percentage string (e.g. "10%"), "normal", or a LetterSpacing instance.	required

Returns:

Type	Description
Self	The Self instance for chaining.

line_height(value)

Sets the line height.

Controls the vertical space each line of text occupies.

Parameters:

Name	Type	Description	Default
value	Union[float, Literal['auto'], LineHeight]	Accepts three forms: float: unitless multiplier applied to the current font_size. A value of 1.5 on a 20 px font yields 30 px per line. Common values: 1.0 (tight), 1.2 (headings), 1.4-1.6 (comfortable reading). "auto": restores the default behaviour: each line height is derived from the font's own metrics (ascent + descent + leading), similar to CSS line-height: normal. LineHeight: a pre-built instance.	required

Returns:

Type	Description
Self	The Self instance for chaining.

Example

Text("Hello").font_size(20).line_height(1.5)
# Each line takes 30 px of vertical space.

Text("Hello").line_height("auto")
# Restores font-metrics-based line height.

text_align(alignment)

Sets the text alignment for multi-line text.

Parameters:

Name	Type	Description	Default
alignment	Union[TextAlign, str]	The alignment, e.g., Alignment.CENTER or "center".	required

Returns:

Type	Description
Self	The Self instance for chaining.

text_wrap(wrap)

Sets how text should wrap within its container.

Parameters:

Name	Type	Description	Default
wrap	Union[TextWrap, str]	The wrapping behavior, e.g., TextWrap.NORMAL or "normal" (allow wrapping), or TextWrap.NOWRAP or "nowrap" (prevent wrapping).	required

Returns:

Type	Description
Self	The Self instance for chaining.

direction(value)

Sets the text direction (horizontal flow).

BiDi algorithm runs automatically regardless of this setting. This property is inherited by child elements.

Parameters:

Name	Type	Description	Default
value	Union[TextDirection, Literal['ltr', 'rtl']]	The text direction, either "ltr" (left-to-right) or "rtl" (right-to-left). Can be a TextDirection enum or a string.	required

Returns:

Type	Description
Self	The Self instance for chaining.

Example

Text("مرحبا").direction("rtl")
Column(
    Text("Text 1"),  # inherits RTL
    Text("Text 2")   # inherits RTL
).direction("rtl")

text_box_edge(both=None, *, top=None, bottom=None)

text_box_edge(both: TextBoxEdgeInput) -> Self

text_box_edge(*, top: TextBoxEdgeInput = ..., bottom: TextBoxEdgeInput = ...) -> Self

Controls how the top and bottom edges of a text node's box are calculated.

By default, PicTex uses font metrics (ascent/descent) to size text boxes. This produces stable, predictable layouts because the box size depends only on the font, ignoring the specific characters in the string.

This method lets you override that behavior per-edge. It is inherited, so setting it on a Canvas or layout container applies to all Text nodes inside.

Note: This property is inspired by the CSS text-box-trim and text-box-edge properties, but does not implement them exactly.

Edge values:

• "font" (default): The edge is placed at the font's ascent (top) or descent (bottom). The box always has the same height for a given font and size, regardless of content. Safe for dynamic / user-supplied text.
• "glyphs": The edge is placed at the actual ink bounds of the rendered glyphs. The box tightly wraps the visible characters, removing the empty space reserved by the font for ascenders/descenders that are not present. Caution: the box size becomes content-dependent, so different strings produce different heights, which can shift your layout unexpectedly.

Parameters:

Name	Type	Description	Default
both	Optional[TextBoxEdgeInput]	Applies the same edge mode to both top and bottom.	None
top	Optional[TextBoxEdgeInput]	Edge mode for the top of the box (keyword-only). Defaults to "font" when omitted.	None
bottom	Optional[TextBoxEdgeInput]	Edge mode for the bottom of the box (keyword-only). Defaults to "font" when omitted.	None

Returns:

Type	Description
Self	The Self instance for chaining.

Raises:

Type	Description
TypeError	If neither both nor at least one of top/bottom are provided, or if both is mixed with top/bottom.

Example

Trim both edges to the glyph ink bounds:

Text("Hello").text_box_edge(TextBoxEdgeValue.GLYPHS)
Text("Hello").text_box_edge("glyphs")

Trim only the top edge, keep font metrics at the bottom:

Text("Hello").text_box_edge(top="glyphs")
Text("Hello").text_box_edge(top="glyphs", bottom="font")  # equivalent

Inherit the setting for all Text nodes in a canvas:

Canvas().text_box_edge("glyphs").render("Hello, World!")

box_shadows(*shadows)

Sets the shadow effects for the element box. This style is not inherited.

This method applies one or more shadows to the box, replacing any previously set box shadows.

Parameters:

Name	Type	Description	Default
*shadows	Shadow	A sequence of one or more Shadow objects to be applied to the box.	()

Returns:

Type	Description
Self	The Self instance for method chaining.

padding(*args)

padding(all: Union[float, int]) -> Self

padding(vertical: Union[float, int], horizontal: Union[float, int]) -> Self

padding(top: Union[float, int], right: Union[float, int], bottom: Union[float, int], left: Union[float, int]) -> Self

Sets padding around the element, similar to CSS.

This method accepts one, two, or four values to specify the padding for the top, right, bottom, and left sides.

Parameters:

Name	Type	Description	Default
*args	Union[float, int]	One value: all four sides. Two values: vertical, horizontal. Four values: top, right, bottom, left.	()

Returns:

Type	Description
Self	The Self instance for chaining.

Raises:

Type	Description
TypeError	If the number of arguments is not 1, 2, or 4.

margin(*args)

margin(all: Union[float, int]) -> Self

margin(vertical: Union[float, int], horizontal: Union[float, int]) -> Self

margin(top: Union[float, int], right: Union[float, int], bottom: Union[float, int], left: Union[float, int]) -> Self

Sets margin around the element, similar to CSS.

This method accepts one, two, or four values to specify the margin for the top, right, bottom, and left sides.

Parameters:

Name	Type	Description	Default
*args	Union[float, int]	One value: all four sides. Two values: vertical, horizontal. Four values: top, right, bottom, left.	()

Returns:

Type	Description
Self	The Self instance for chaining.

Raises:

Type	Description
TypeError	If the number of arguments is not 1, 2, or 4.

padding_top(value)

Sets the top padding, preserving the other three sides.

padding_right(value)

Sets the right padding, preserving the other three sides.

padding_bottom(value)

Sets the bottom padding, preserving the other three sides.

padding_left(value)

Sets the left padding, preserving the other three sides.

padding_horizontal(value)

Sets left and right padding equally, preserving top and bottom.

padding_vertical(value)

Sets top and bottom padding equally, preserving left and right.

margin_top(value)

Sets the top margin, preserving the other three sides.

margin_right(value)

Sets the right margin, preserving the other three sides.

margin_bottom(value)

Sets the bottom margin, preserving the other three sides.

margin_left(value)

Sets the left margin, preserving the other three sides.

margin_horizontal(value)

Sets left and right margin equally, preserving top and bottom.

margin_vertical(value)

Sets top and bottom margin equally, preserving left and right.

background_color(color)

Sets the background color or gradient.

Parameters:

Name	Type	Description	Default
color	Union[str, PaintSource]	A color string or a PaintSource object.	required

Returns:

Type	Description
Self	The Self instance for chaining.

background_image(path, size_mode=BackgroundImageSizeMode.COVER)

Sets a background image for the element.

Parameters:

Name	Type	Description	Default
path	str	The path to the image file.	required
size_mode	Union[BackgroundImageSizeMode, str]	The fitting strategy. Can be 'cover', 'contain', or 'tile'. - 'cover': The image is resized to completely cover the element's box, maintaining its aspect ratio. The image may be cropped. - 'contain': The image is resized to fit entirely within the box, maintaining its aspect ratio. This may leave empty space. - 'tile': The image is tiled at its original size without resizing.	COVER

Returns:

Name	Type	Description
Self	Self	The instance for method chaining.

border(width, color, style=BorderStyle.SOLID)

Sets the border for the element.

Parameters:

Name	Type	Description	Default
width	float	The width of the border in pixels.	required
color	Union[str, PaintSource]	The color of the border (e.g., "red", "#FF0000") or a PaintSource object.	required
style	Union[str, BorderStyle]	The style of the borderline. Can be 'solid', 'dashed', or 'dotted'.	SOLID

Returns:

Type	Description
Self	The Self instance for method chaining.

border_radius(*args)

border_radius(all: Union[float, str]) -> Self

border_radius(top_bottom: Union[float, str], left_right: Union[float, str]) -> Self

border_radius(top_left: Union[float, str], top_right: Union[float, str], bottom_right: Union[float, str], bottom_left: Union[float, str]) -> Self

Sets the corner radius for the background, similar to CSS border-radius. Accepts absolute values (pixels) or percentages as strings (e.g., "50%").

Parameters:

Name	Type	Description	Default
*args	Union[float, str]	One value: all four corners. Two values: [top-left, bottom-right], [top-right, bottom-left]. Four values: [top-left], [top-right], [bottom-right], [bottom-left].	()

Returns:

Type	Description
Self	The Self instance for chaining.

flex_grow(value)

Sets the flex grow factor for this element (CSS flex-grow).

Controls how much this element should grow relative to siblings when there's extra space in the flex container.

Parameters:

Name	Type	Description	Default
value	float	The grow factor. 0 means no growth (default), 1+ means grow. Higher values grow proportionally more.	required

Returns:

Type	Description
Self	The Self instance for chaining.

Example

Row(
    Text("Fixed").size(width=100),
    Text("Grows x1").flex_grow(1),
    Text("Grows x2").flex_grow(2)
)

flex_shrink(value)

Sets the flex shrink factor for this element (CSS flex-shrink).

Controls how much this element should shrink relative to siblings when the container is too small.

Parameters:

Name	Type	Description	Default
value	float	The shrink factor. 0 means no shrinking, 1 means shrink proportionally (default). Higher values shrink more.	required

Returns:

Type	Description
Self	The Self instance for chaining.

Example

Row(
    Text("Don't shrink").flex_shrink(0),
    Text("Can shrink").flex_shrink(1)
)

align_self(alignment)

Override the container's align-items for this specific element (CSS align-self).

Allows an individual flex item to override the alignment set by its container.

Parameters:

Name	Type	Description	Default
alignment	Union[AlignSelf, str]	Alignment mode. Can be 'auto', 'start', 'center', 'end', or 'stretch'. 'auto' uses the container's align-items value (default).	required

Returns:

Type	Description
Self	The Self instance for chaining.

Example

Row(
    Text("A"),
    Text("B").align_self('end'),  # This one aligns differently
    Text("C")
).align_items('start')

overflow(value)

Controls how content that exceeds the element's bounds is rendered.

Equivalent to CSS overflow. When set to "hidden", any content (text, child nodes, images) that extends beyond the element's padding box is clipped and hidden. The background and border are not affected by the clip.

This property is not inherited.

Parameters:

Name	Type	Description	Default
value	Union[Overflow, Literal['hidden', 'visible']]	"hidden" to clip overflowing content, or "visible" to leave it unclipped (the default). Accepts the Overflow enum or its string equivalents.	required

Returns:

Type	Description
Self	The Self instance for chaining.

Example

# Clip text that overflows a fixed-size box:
Text("Very long text…").size(width=200, height=50).overflow("hidden")

# Clip children that grow beyond a container:
Row(child1, child2).size(width=300).overflow("hidden")

gap(value)

Sets a fixed space between each child element along the main axis.

This is often simpler than adding margins to each child individually.

Parameters:

Name	Type	Description	Default
value	float	The space, in pixels, to add between children.	required

Returns:

Type	Description
Self	The Self instance for chaining.

justify_content(mode)

Sets how children are distributed along the main axis (CSS justify-content).

For Row: controls horizontal distribution. For Column: controls vertical distribution.

Parameters:

Name	Type	Description	Default
mode	Union[JustifyContent, str]	Distribution mode. Can be 'start', 'center', 'end', 'space-between', 'space-around', or 'space-evenly'.	required

Returns:

Type	Description
Self	The Self instance for chaining.

align_items(mode)

Sets how children are aligned along the cross axis (CSS align-items).

For Row: controls vertical alignment. For Column: controls horizontal alignment.

Parameters:

Name	Type	Description	Default
mode	Union[AlignItems, str]	Alignment mode. Can be 'start', 'center', 'end', or 'stretch'.	required

Returns:

Type	Description
Self	The Self instance for chaining.

flex_wrap(mode)

Sets whether children should wrap when they overflow (CSS flex-wrap).

Enables multi-line flex containers, essential for responsive grid-like layouts.

Parameters:

Name	Type	Description	Default
mode	Union[FlexWrap, str]	Wrap mode. Can be 'nowrap' (default), 'wrap', or 'wrap-reverse'. - 'nowrap': All children stay on one line - 'wrap': Children wrap to new lines when needed - 'wrap-reverse': Children wrap in reverse order	required

Returns:

Type	Description
Self	The Self instance for chaining.

Example

Row(
    *[Text(f"Item {i}").size(width=100) for i in range(20)]
).flex_wrap('wrap').size(width=500)  # Creates a grid