The Modifier API: Composable Layout and Style in Svelte

Every component in Compose Svelted accepts a modifier prop. Rather than scattering inline styles or class names across your markup, you describe what you want — padding, clipping, scrollability, click handling — through a fluent, immutable chain of calls. Modifiers do not produce CSS directly at the call site; they accumulate declarative intent that the component runtime resolves into styles and classes when it renders.

The `Modifier` object

Modifier is a plain TypeScript object that exposes every modifier factory as a static method. Each call returns a new ModifierImpl instance — nothing is mutated. You can store modifiers in variables, compose them with .then(), or pass them directly as props.

import { Modifier } from "@danielito1996/compose-svelted";

// The zero-value: no styles, no classes, no side-effects
const base = Modifier.empty();

// A real modifier chain
const card = Modifier
  .padding(16)
  .fillMaxWidth()
  .clip(RoundedCornerShape(12))
  .background("var(--md-sys-color-surface)");

The `PaddingValue` type

The padding() method accepts either a plain number (uniform padding on all four sides) or an object that specifies individual sides. All values default to 0 when omitted.

type PaddingValue =
  | number
  | {
      top?: number;
      bottom?: number;
      start?: number; // maps to padding-left
      end?: number;   // maps to padding-right
    };

Method reference

Every method is available both on the static Modifier entry-point and on the ModifierImpl instance it returns, so chains of any length work naturally.

Padding and spacing

padding(valueOrParams, unit?)

PaddingValue, string = 'px'

Applies uniform padding when passed a number, or per-side padding when passed an object with optional top, bottom, start, and end keys. The unit parameter (default "px") is only used when valueOrParams is a number or when the individual side values are numbers.

Modifier.padding(16)
Modifier.padding({ top: 8, bottom: 8, start: 16, end: 16 })
Modifier.padding(1.5, "rem")

paddingHorizontal(value)

number

Applies equal padding to the left and right sides. Unit is always px.

Modifier.paddingHorizontal(24)

paddingVertical(value)

number

Applies equal padding to the top and bottom sides. Unit is always px.

Modifier.paddingVertical(12)

marginTop(value, unit?)

number, string = 'px'

Adds a top margin. Useful for creating vertical spacing between siblings without wrapping them in a layout container.

Modifier.marginTop(8)
Modifier.marginTop(1, "rem")

Sizing

fillMaxWidth()

—

Expands the element to fill its container’s full width (width: 100%; align-self: stretch).

Modifier.fillMaxWidth()

fillMaxHeight()

—

Expands the element to fill its container’s full height (height: 100%; align-self: stretch).

Modifier.fillMaxHeight()

fillMaxSize()

—

Combines fillMaxWidth and fillMaxHeight: the element fills both axes of its container.

Modifier.fillMaxSize()

width(value, unit?)

number | string, string = 'px'

Sets an explicit width. Pass a number for pixel values, or a pre-formed CSS string such as "50%" or "auto".

Modifier.width(200)
Modifier.width("50%")
Modifier.width(20, "rem")

height(value, unit?)

number | string, string = 'px'

Sets an explicit height. Accepts the same forms as width().

Modifier.height(120)
Modifier.height("100vh")

size(value, unit?)

number | string, string = 'px'

Sets both width and height to the same value — shorthand for a square or circle.

Modifier.size(48)        // 48 × 48 px avatar
Modifier.size(3, "rem")

weight(weight, fill?)

number, boolean = true

Participates in flex growth. The weight value maps directly to flex-grow. When fill is true (the default), flex-shrink is 1, allowing the element to also shrink; when false, it only grows. Values of 0 or below are silently ignored.

// Two children that share space 2:1
Modifier.weight(2)
Modifier.weight(1)

weightNoFill(weight)

number

Convenience alias for weight(weight, false). The element grows at the given ratio but will not shrink below its intrinsic size.

Modifier.weightNoFill(1)

Appearance

background(color)

ColorToken | string

Sets the background colour. Accepts a raw CSS colour string or a ColorToken key (e.g. ColorScheme.Primary), which is automatically resolved to the corresponding CSS custom property at render time.

import { Modifier, ColorScheme } from "@danielito1996/compose-svelted";

Modifier.background(ColorScheme.Surface)
Modifier.background("#FF732F")

border(width, color, shape?)

number, string, Shape?

Draws a solid border. Optionally accepts a Shape (e.g. RoundedCornerShape) to apply matching border-radius. Widths of 0 or below are silently ignored.

Modifier.border(1, "#B0B0B0")
Modifier.border(2, "#FF732F", RoundedCornerShape(8))

clip(shape)

Shape

Clips the element to the given shape by applying border-radius and overflow: hidden. Use RoundedCornerShape to create the shape.

Modifier.clip(RoundedCornerShape(12))
Modifier.clip(RoundedCornerShape({ topStart: 16, topEnd: 16 }))

Position and transform

offset(x, y)

number, number

Translates the element by (x, y) pixels using a CSS transform: translate(). Does not affect layout flow — other elements remain in their computed positions.

Modifier.offset(0, -4)   // nudge 4 px upward
Modifier.offset(8, 0)    // nudge 8 px to the right

align(alignment)

BoxAlignment | HorizontalAlignment | VerticalAlignment

Overrides the cross-axis alignment of a single child within its parent container. The alignment token type must be compatible with the parent: HorizontalAlignment inside a Column, VerticalAlignment inside a Row, and BoxAlignment inside a Box.

import { Modifier, Alignment } from "@danielito1996/compose-svelted";

// Inside a Column — align one child to the end
Modifier.align(Alignment.End)

// Inside a Row — push one child to the bottom
Modifier.align(Alignment.Bottom)

Scroll

verticalScroll(enabled?)

boolean = true

Makes the element scrollable along the vertical axis (overflow-y: auto). Passing false is a no-op and returns the modifier unchanged.

Modifier.fillMaxHeight().verticalScroll()

horizontalScroll(enabled?)

boolean = true

Makes the element scrollable along the horizontal axis (overflow-x: auto). Passing false is a no-op and returns the modifier unchanged.

Modifier.horizontalScroll()

Interaction

clickable(onClick?)

() => void

Marks the element as interactive by adding the compose-clickable CSS class and the styles cursor: pointer; user-select: none. Pass an onClick handler to react to clicks.

Modifier.clickable(() => console.log("tapped"))

Chaining modifiers

then(other)

ModifierImpl

Merges another ModifierImpl onto the end of the current one, producing a new immutable instance. This is the primitive that all chained method calls use internally. Use it directly when you want to combine two pre-built modifier values.

const base = Modifier.padding(16).fillMaxWidth();
const interactive = Modifier.clickable(() => alert("hi"));

const combined = base.then(interactive);

Passing modifiers to components

Every Compose Svelted layout and widget component accepts a modifier prop typed as Modifier (which is an alias for ModifierImpl). Pass your chain directly:

<script lang="ts">
  import { Box, Modifier, RoundedCornerShape, ColorScheme }
    from "@danielito1996/compose-svelted";
</script>

<Box
  modifier={Modifier
    .fillMaxWidth()
    .padding({ top: 24, bottom: 24, start: 16, end: 16 })
    .clip(RoundedCornerShape(16))
    .background(ColorScheme.SurfaceVariant)}
>
  <!-- children -->
</Box>

You can also factor shared modifiers into variables and reuse them across components:

<script lang="ts">
  import { Column, Text, Modifier } from "@danielito1996/compose-svelted";

  const cardModifier = Modifier
    .fillMaxWidth()
    .padding(16)
    .clip(RoundedCornerShape(12));
</script>

<Column modifier={cardModifier}>
  <Text>Card content</Text>
</Column>

Internal methods: `toStyle()` and `toClass()`

ModifierImpl exposes two methods that are used internally by the component runtime — you will rarely need to call them yourself.

toStyle(): string — Concatenates all accumulated inline style strings from the modifier entries, then appends any alignment style derived from a .align() call. Returns a single CSS string ready to set on a DOM element’s style attribute.
toClass(): string — Collects all CSS class names added by modifier entries (e.g. "compose-clickable") and joins them into a space-separated string.

Both methods are read-only and produce no side effects; they can be called multiple times on the same instance.

Get Started

Core Concepts

Layout Components

UI Components

Motion

Navigation

Examples

The Modifier API: Composable Layout and Style in Svelte

The `Modifier` object

The `PaddingValue` type

Method reference

Padding and spacing

Sizing

Appearance

Position and transform

Scroll

Interaction

Chaining modifiers

Passing modifiers to components

Internal methods: `toStyle()` and `toClass()`

Build docs developers (and LLMs) love

Get Started

Core Concepts

Layout Components

UI Components

Motion

Navigation

Examples

Documentation Index

​The Modifier object

​The PaddingValue type

​Method reference

​Padding and spacing

​Sizing

​Appearance

​Position and transform

​Scroll

​Interaction

​Chaining modifiers

​Passing modifiers to components

​Internal methods: toStyle() and toClass()

Build docs developers (and LLMs) love

The `Modifier` object

The `PaddingValue` type

Method reference

Padding and spacing

Sizing

Appearance

Position and transform

Scroll

Interaction

Chaining modifiers

Passing modifiers to components

Internal methods: `toStyle()` and `toClass()`