Modifier API ReferenceThis document provides detailed information about the Modifier system in the Summon library. Modifiers are used to applystyling, layout, and behavior to components in a type-safe, composable way.

Modifier API Reference

This document provides detailed information about the Modifier system in the Summon library. Modifiers are used to apply styling, layout, and behavior to components in a type-safe, composable way.

Table of Contents

Core Modifier Class

The Modifier is a data class that holds CSS styles and HTML attributes.

Class Definition

@JsExport
data class Modifier(
    val styles: Map<String, String> = emptyMap(),
    val attributes: Map<String, String> = emptyMap()
) {
    // Generic style method
    fun style(propertyName: String, value: String): Modifier

    // Batch style application
    fun withStyles(properties: Map<String, String>): Modifier

    // Core styling methods
    fun background(color: String): Modifier
    fun backgroundColor(color: String): Modifier
    fun padding(value: String): Modifier
    fun padding(top: String, right: String, bottom: String, left: String): Modifier
    fun width(value: String): Modifier
    fun height(value: String): Modifier
    fun margin(value: String): Modifier
    fun color(value: String): Modifier
    fun fontSize(value: String): Modifier
    fun fontWeight(value: String): Modifier
    fun textAlign(value: String): Modifier
    fun border(width: String, style: String, color: String): Modifier
    fun borderRadius(value: String): Modifier
    fun display(value: String): Modifier

    // Layout utilities
    fun fillMaxWidth(): Modifier
    fun fillMaxHeight(): Modifier
}

Factory Function

// Create a new modifier
fun Modifier(): Modifier = Modifier(emptyMap(), emptyMap())

Basic Usage

val modifier = Modifier()
    .width("200px")
    .height("100px")
    .backgroundColor("#007bff")
    .color("#ffffff")
    .padding("16px")
    .borderRadius("4px")

CSS Units Extensions

Summon provides convenient extension properties for creating CSS values with proper units.

Number Extensions

// Extension properties in code.yousef.summon.extensions
val Number.px: String      // Pixels: 16.px -> "16px"
val Number.rem: String     // Root em: 1.5.rem -> "1.5rem"
val Number.em: String      // Em units: 1.2.em -> "1.2em"
val Number.percent: String // Percentage: 50.percent -> "50%"
val Number.vw: String      // Viewport width: 100.vw -> "100vw"
val Number.vh: String      // Viewport height: 100.vh -> "100vh"
val Number.vmin: String    // Viewport minimum: 50.vmin -> "50vmin"
val Number.vmax: String    // Viewport maximum: 50.vmax -> "50vmax"
val Number.sp: String      // Scale-independent pixels: 14.sp -> "14sp"
val Number.ch: String      // Character width: 2.ch -> "2ch"
val Number.ex: String      // X-height: 3.ex -> "3ex"
val Number.pt: String      // Points: 12.pt -> "12pt"
val Number.pc: String      // Picas: 6.pc -> "6pc"

Usage Examples

import code.yousef.summon.extensions.*

Modifier()
    .width(100.percent)
    .height(50.vh)
    .padding(16.px)
    .fontSize(1.2.rem)
    .margin(8.px, 16.px, 8.px, 16.px)

Layout Modifiers

Layout modifiers control size, spacing, and positioning.

Size Modifiers

// Basic dimensions
fun Modifier.width(value: String): Modifier
fun Modifier.height(value: String): Modifier
fun Modifier.minWidth(value: String): Modifier
fun Modifier.minHeight(value: String): Modifier
fun Modifier.maxWidth(value: String): Modifier
fun Modifier.maxHeight(value: String): Modifier

// Fill utilities
fun Modifier.fillMaxWidth(): Modifier = width("100%")
fun Modifier.fillMaxHeight(): Modifier = height("100%")
fun Modifier.fillMaxSize(): Modifier = fillMaxWidth().fillMaxHeight()

Padding Modifiers

// Uniform padding
fun Modifier.padding(value: String): Modifier

// Directional padding
fun Modifier.padding(top: String, right: String, bottom: String, left: String): Modifier
fun Modifier.padding(vertical: String, horizontal: String): Modifier
fun Modifier.paddingTop(value: String): Modifier
fun Modifier.paddingRight(value: String): Modifier
fun Modifier.paddingBottom(value: String): Modifier
fun Modifier.paddingLeft(value: String): Modifier

// Named parameters
fun Modifier.paddingOf(
    top: String? = null,
    right: String? = null,
    bottom: String? = null,
    left: String? = null
): Modifier

Margin Modifiers

// Uniform margin
fun Modifier.margin(value: String): Modifier

// Directional margin
fun Modifier.margin(top: String, right: String, bottom: String, left: String): Modifier
fun Modifier.margin(vertical: String, horizontal: String): Modifier
fun Modifier.marginTop(value: String): Modifier
fun Modifier.marginRight(value: String): Modifier
fun Modifier.marginBottom(value: String): Modifier
fun Modifier.marginLeft(value: String): Modifier

// Named parameters
fun Modifier.marginOf(
    top: String? = null,
    right: String? = null,
    bottom: String? = null,
    left: String? = null
): Modifier

// Convenience helper
fun Modifier.centerHorizontally(vertical: String = "0"): Modifier

CSS Function Helpers

fun cssMin(vararg values: CssValue): CssValue
fun cssMax(vararg values: CssValue): CssValue
fun cssClamp(min: CssValue, preferred: CssValue, max: CssValue): CssValue

Use the existing numeric extensions (e.g., 22.px, 4.vw, 48.px) from code.yousef.summon.extensions.* to produce CssValue instances that can be passed to these helpers and then into modifiers like fontSize, padding, or width.

Position Modifiers

// Position type
fun Modifier.position(value: Position): Modifier
fun Modifier.position(value: String): Modifier

// Position values
fun Modifier.top(value: String): Modifier
fun Modifier.right(value: String): Modifier
fun Modifier.bottom(value: String): Modifier
fun Modifier.left(value: String): Modifier

// Z-index
fun Modifier.zIndex(value: String): Modifier
fun Modifier.zIndex(value: Int): Modifier

// Inset shorthand
fun Modifier.inset(value: String): Modifier
fun Modifier.inset(vertical: String, horizontal: String): Modifier
fun Modifier.inset(top: String, right: String, bottom: String, left: String): Modifier
fun Modifier.positionInset(
    top: String? = null,
    right: String? = null,
    bottom: String? = null,
    left: String? = null
): Modifier

// Aspect ratio
fun Modifier.aspectRatio(ratio: Number): Modifier
fun Modifier.aspectRatio(width: Number, height: Number): Modifier

Usage Examples

// Size and spacing
Modifier()
    .width(300.px)
    .minHeight(200.px)
    .padding(16.px)
    .margin(vertical = 8.px, horizontal = 16.px)

// Positioning
Modifier()
    .position(Position.Absolute)
    .top(10.px)
    .right(10.px)
    .zIndex(100)

// Centering
Modifier()
    .width(200.px)
    .centerHorizontally()

Styling Modifiers

Visual styling modifiers for appearance and typography.

Background and Colors

// Background
fun Modifier.background(color: String): Modifier
fun Modifier.backgroundColor(color: String): Modifier
fun Modifier.backgroundImage(url: String): Modifier
fun Modifier.backgroundSize(value: String): Modifier
fun Modifier.backgroundRepeat(value: String): Modifier
fun Modifier.backgroundPosition(value: String): Modifier
fun Modifier.backgroundLayers(vararg layers: GradientLayer): Modifier
fun Modifier.backgroundLayers(builder: GradientLayerScope.() -> Unit): Modifier
fun Modifier.backgroundBlendModes(vararg modes: BlendMode): Modifier
fun Modifier.backgroundBlendModes(value: String): Modifier
fun Modifier.backgroundClip(value: BackgroundClip): Modifier
fun Modifier.backgroundClipText(includeWebkitPrefix: Boolean = true): Modifier

// Text color
fun Modifier.color(value: String): Modifier

GradientLayerScope exposes radialGradient, linearGradient, conicGradient, and image/url helpers so complex multi-layer backgrounds can be expressed with type-safe builders instead of composing raw CSS strings.

Typography Modifiers

// Font properties
fun Modifier.fontSize(value: String): Modifier
fun Modifier.fontSize(value: Number): Modifier
fun Modifier.fontWeight(value: String): Modifier
fun Modifier.fontWeight(value: FontWeight): Modifier
fun Modifier.fontFamily(value: String): Modifier
fun Modifier.fontStyle(value: String): Modifier
fun Modifier.fontStyle(value: FontStyle): Modifier

// Text styling
fun Modifier.textAlign(value: String): Modifier
fun Modifier.textAlign(value: TextAlign): Modifier
fun Modifier.textDecoration(value: String): Modifier
fun Modifier.textDecoration(value: TextDecoration): Modifier
fun Modifier.textDecoration(vararg values: TextDecoration): Modifier
fun Modifier.textTransform(value: String): Modifier
fun Modifier.textTransform(value: TextTransform): Modifier
fun Modifier.lineHeight(value: String): Modifier
fun Modifier.lineHeight(value: Number): Modifier
fun Modifier.letterSpacing(value: String): Modifier
fun Modifier.letterSpacing(value: Number): Modifier
fun Modifier.whiteSpace(value: String): Modifier
fun Modifier.whiteSpace(value: WhiteSpace): Modifier

Border Modifiers

// Complete border
fun Modifier.border(width: String, style: String, color: String): Modifier
fun Modifier.border(value: String): Modifier

// Border sides
fun Modifier.borderTop(value: String): Modifier
fun Modifier.borderRight(value: String): Modifier
fun Modifier.borderBottom(value: String): Modifier
fun Modifier.borderLeft(value: String): Modifier

// Border properties
fun Modifier.borderWidth(value: String): Modifier
fun Modifier.borderStyle(value: String): Modifier
fun Modifier.borderColor(value: String): Modifier
fun Modifier.borderRadius(value: String): Modifier

// Rounded corners
fun Modifier.rounded(radius: String = "4px"): Modifier
fun Modifier.roundedTop(radius: String): Modifier
fun Modifier.roundedBottom(radius: String): Modifier

Display and Layout

// Display type
fun Modifier.display(value: String): Modifier
fun Modifier.display(value: Display): Modifier

// Visibility
fun Modifier.visibility(value: String): Modifier
fun Modifier.opacity(value: String): Modifier
fun Modifier.opacity(value: Double): Modifier

// Overflow
fun Modifier.overflow(value: String): Modifier
fun Modifier.overflow(value: Overflow): Modifier
fun Modifier.overflowX(value: String): Modifier
fun Modifier.overflowY(value: String): Modifier

Flexbox Modifiers

// Flex container
fun Modifier.flexDirection(value: String): Modifier
fun Modifier.flexDirection(value: FlexDirection): Modifier
fun Modifier.justifyContent(value: String): Modifier
fun Modifier.justifyContent(value: JustifyContent): Modifier
fun Modifier.alignItems(value: String): Modifier
fun Modifier.alignItems(value: AlignItems): Modifier
fun Modifier.alignContent(value: String): Modifier
fun Modifier.flexWrap(value: String): Modifier
fun Modifier.gap(value: String): Modifier
fun Modifier.flex(grow: Number, shrink: Number, basis: String): Modifier

// Flex items
fun Modifier.flexGrow(value: String): Modifier
fun Modifier.flexGrow(value: Number): Modifier
fun Modifier.flexShrink(value: String): Modifier
fun Modifier.flexBasis(value: String): Modifier
fun Modifier.alignSelf(value: String): Modifier
fun Modifier.order(value: Int): Modifier

Usage Examples

// Styling
Modifier()
    .backgroundColor("#f8f9fa")
    .color("#212529")
    .fontSize(16.px)
    .fontWeight(FontWeight.Medium)
    .border("1px", "solid", "#dee2e6")
    .borderRadius(8.px)
    .opacity(0.9)

// Flexbox layout
Modifier()
    .display(Display.Flex)
    .flexDirection(FlexDirection.Column)
    .justifyContent(JustifyContent.Center)
    .alignItems(AlignItems.Center)
    .gap(16.px)

CSS Enums

Type-safe enums for common CSS values.

Layout Enums

enum class Display(val value: String) {
    None("none"), Block("block"), Inline("inline"),
    InlineBlock("inline-block"), Flex("flex"), Grid("grid"),
    InlineFlex("inline-flex"), InlineGrid("inline-grid")
}

enum class Position(val value: String) {
    Static("static"), Relative("relative"), Absolute("absolute"),
    Fixed("fixed"), Sticky("sticky")
}

enum class Overflow(val value: String) {
    Visible("visible"), Hidden("hidden"),
    Scroll("scroll"), Auto("auto")
}

Flexbox Enums

enum class FlexDirection(val value: String) {
    Row("row"), RowReverse("row-reverse"),
    Column("column"), ColumnReverse("column-reverse")
}

enum class JustifyContent(val value: String) {
    FlexStart("flex-start"), FlexEnd("flex-end"), Center("center"),
    SpaceBetween("space-between"), SpaceAround("space-around"),
    SpaceEvenly("space-evenly")
}

enum class AlignItems(val value: String) {
    FlexStart("flex-start"), FlexEnd("flex-end"), Center("center"),
    Baseline("baseline"), Stretch("stretch")
}

Typography Enums

enum class FontWeight(val value: String) {
    Thin("100"), ExtraLight("200"), Light("300"), Normal("400"),
    Medium("500"), SemiBold("600"), Bold("700"),
    ExtraBold("800"), Black("900")
}

enum class TextAlign(val value: String) {
    Left("left"), Right("right"), Center("center"),
    Justify("justify"), Start("start"), End("end")
}

Usage Examples

Modifier()
    .display(Display.Flex)
    .position(Position.Relative)
    .flexDirection(FlexDirection.Column)
    .justifyContent(JustifyContent.Center)
    .alignItems(AlignItems.Center)
    .fontWeight(FontWeight.Bold)
    .textAlign(TextAlign.Center)
    .overflow(Overflow.Hidden)

Accessibility Modifiers

Modifiers for accessibility attributes and ARIA support.

ARIA Attributes

// ARIA properties
fun Modifier.ariaLabel(value: String): Modifier
fun Modifier.ariaDescribedBy(value: String): Modifier
fun Modifier.ariaLabelledBy(value: String): Modifier
fun Modifier.ariaHidden(value: Boolean): Modifier
fun Modifier.ariaExpanded(value: Boolean): Modifier
fun Modifier.ariaPressed(value: Boolean): Modifier
fun Modifier.ariaChecked(value: Boolean): Modifier
fun Modifier.ariaSelected(value: Boolean): Modifier
fun Modifier.ariaDisabled(value: Boolean): Modifier

// Role attribute
fun Modifier.role(value: String): Modifier

Focus Modifiers

// Focus styling
fun Modifier.focus(modifier: Modifier): Modifier
fun Modifier.focusVisible(modifier: Modifier): Modifier
fun Modifier.tabIndex(value: Int): Modifier

Usage Examples

Modifier()
    .ariaLabel("Close dialog")
    .role("button")
    .tabIndex(0)
    .focus(
        Modifier()
            .borderColor("#007bff")
            .outline("2px solid #007bff")
    )

Interactive Modifiers

Modifiers for user interactions and state changes.

Hover and Active States

// Pseudo-class modifiers
fun Modifier.hover(modifier: Modifier): Modifier
fun Modifier.active(modifier: Modifier): Modifier
fun Modifier.focus(modifier: Modifier): Modifier
fun Modifier.visited(modifier: Modifier): Modifier
fun Modifier.disabled(modifier: Modifier): Modifier

Cursor Modifiers

// Cursor styles
fun Modifier.cursor(value: String): Modifier
fun Modifier.cursor(value: Cursor): Modifier

enum class Cursor(val value: String) {
    Auto("auto"), Default("default"), Pointer("pointer"),
    Text("text"), Wait("wait"), Help("help"), NotAllowed("not-allowed")
}

Pointer Events

// Pointer event handling
fun Modifier.pointerEvents(value: String): Modifier
fun Modifier.userSelect(value: String): Modifier

Usage Examples

// Interactive button
Modifier()
    .cursor(Cursor.Pointer)
    .hover(
        Modifier()
            .backgroundColor("#0056b3")
            .transform("translateY(-2px)")
    )
    .active(
        Modifier().backgroundColor("#004085")
    )
    .focus(
        Modifier().outline("2px solid #80bdff")
    )

Advanced Modifiers

Advanced styling capabilities for complex designs.

Transform Modifiers

// Transform functions
fun Modifier.transform(value: String): Modifier
fun Modifier.rotate(degrees: String): Modifier
fun Modifier.scale(value: String): Modifier
fun Modifier.translate(x: String, y: String): Modifier
fun Modifier.skew(x: String, y: String): Modifier

Animation and Transition

// Transitions
fun Modifier.transition(value: String): Modifier
fun Modifier.transitionProperty(value: String): Modifier
fun Modifier.transitionDuration(value: String): Modifier
fun Modifier.transitionDelay(value: String): Modifier
fun Modifier.transitionTimingFunction(value: String): Modifier

// Animations
fun Modifier.animation(value: String): Modifier
fun Modifier.animationName(value: String): Modifier
fun Modifier.animationDuration(value: String): Modifier
fun Modifier.animationDelay(value: String): Modifier
fun Modifier.animationIterationCount(value: String): Modifier

Pseudo-element Modifiers

fun Modifier.before(
    ensurePositionRelative: Boolean = true,
    content: String? = null,
    builder: Modifier.() -> Modifier
): Modifier

fun Modifier.after(
    ensurePositionRelative: Boolean = true,
    content: String? = null,
    builder: Modifier.() -> Modifier
): Modifier

Both helpers collect modifier styles for their respective pseudo-element and automatically inject a data-summon-id + scoped <style> rule during rendering, which keeps background glows and grain overlays encapsulated without manual DOM nodes.

Shadow and Effects

// Shadows
fun Modifier.boxShadow(value: String): Modifier
fun Modifier.textShadow(value: String): Modifier
fun Modifier.dropShadow(value: String): Modifier

// Filters
fun Modifier.filter(value: String): Modifier
fun Modifier.backdropFilter(value: String): Modifier
fun Modifier.filter(function: FilterFunction, value: String): Modifier
fun Modifier.filter(function: FilterFunction, value: Number, unit: String): Modifier
fun Modifier.filter(builder: FilterBuilder.() -> Unit): Modifier
fun Modifier.backdropFilter(builder: FilterBuilder.() -> Unit): Modifier
fun Modifier.mixBlendMode(value: String): Modifier
fun Modifier.mixBlendMode(value: BlendMode): Modifier

The builder overloads accept blur/brightness/contrast/hue-rotate/drop-shadow steps, mirroring the CSS filter functions available to the raw string helpers.

Grid Layout

// Grid container
fun Modifier.gridTemplateColumns(value: String): Modifier
fun Modifier.gridTemplateRows(value: String): Modifier
fun Modifier.gridTemplateAreas(value: String): Modifier
fun Modifier.gridGap(value: String): Modifier
fun Modifier.gridAutoColumns(value: String): Modifier
fun Modifier.gridAutoRows(value: String): Modifier

// Grid items
fun Modifier.gridColumn(value: String): Modifier
fun Modifier.gridRow(value: String): Modifier
fun Modifier.gridArea(value: String): Modifier
fun Modifier.justifySelf(value: String): Modifier
fun Modifier.alignSelf(value: String): Modifier

Usage Examples

// Card with advanced styling
Modifier()
    .backgroundColor("#ffffff")
    .borderRadius(12.px)
    .boxShadow("0 4px 6px rgba(0, 0, 0, 0.1)")
    .transition("all 0.3s ease")
    .hover(
        Modifier()
            .transform("translateY(-4px)")
            .boxShadow("0 8px 25px rgba(0, 0, 0, 0.15)")
    )

// Grid layout
Modifier()
    .display(Display.Grid)
    .gridTemplateColumns("repeat(auto-fit, minmax(200px, 1fr))")
    .gridGap(20.px)
    .padding(20.px)

Theme Integration

Modifiers integrate seamlessly with the Summon theme system.

Theme Modifier Extensions

// Theme-aware modifiers from theme system
fun Modifier.themeColor(colorName: String): Modifier
fun Modifier.themeBackgroundColor(colorName: String): Modifier
fun Modifier.themeTextStyle(styleName: String): Modifier
fun Modifier.themePadding(spacingName: String): Modifier
fun Modifier.themeMargin(spacingName: String): Modifier
fun Modifier.themeBorderRadius(radiusName: String): Modifier
fun Modifier.themeElevation(elevationName: String): Modifier

Usage with Themes

// Using theme values
Modifier()
    .themeBackgroundColor("primary")
    .themeColor("onPrimary")
    .themeTextStyle("button")
    .themePadding("md")
    .themeBorderRadius("sm")
    .themeElevation("md")

// Mixed with direct styling
Modifier()
    .themeBackgroundColor("surface")
    .width(100.percent)
    .hover(
        Modifier().themeBackgroundColor("surfaceVariant")
    )

Pseudo-Selector Modifiers

Apply styles based on element state and structural position using pseudo-selectors.

Interactive State Selectors

// Hover state
Box(
    modifier = Modifier()
        .backgroundColor("#f0f0f0")
        .hover(Modifier().backgroundColor("#e0e0e0"))
)

// Focus state
TextField(
    modifier = Modifier()
        .outlineColor("gray")
        .focus(Modifier().outlineColor("blue"))
)

// Active state (being clicked)
Button(
    modifier = Modifier()
        .backgroundColor("#007bff")
        .active(Modifier().backgroundColor("#0056b3"))
)

// Focus-within (element or descendants have focus)
Box(
    modifier = Modifier()
        .borderColor("gray")
        .focusWithin(Modifier().borderColor("blue"))
)

Structural Selectors

// First child
Box(
    modifier = Modifier()
        .firstChild(Modifier().marginTop("0px"))
)

// Last child
Box(
    modifier = Modifier()
        .lastChild(Modifier().marginBottom("0px"))
)

// Nth child
Box(
    modifier = Modifier()
        .nthChild("2n", Modifier().backgroundColor("#f5f5f5")) // Even rows
        .nthChild("odd", Modifier().backgroundColor("white"))   // Odd rows
)

// Only child
Box(
    modifier = Modifier()
        .onlyChild(Modifier().margin("0 auto"))
)

State Selectors

// Visited links
Link(
    modifier = Modifier()
        .color("blue")
        .visited(Modifier().color("purple"))
)

// Disabled state
Button(
    modifier = Modifier()
        .disabledStyles(Modifier()
            .backgroundColor("gray")
            .cursor("not-allowed")
        )
)

// Checked state (checkboxes/radios)
Checkbox(
    modifier = Modifier()
        .checkedStyles(Modifier().backgroundColor("blue"))
)

Using Map Syntax

All pseudo-selectors support map-based syntax:

Modifier().hover(mapOf(
    "background-color" to "#e0e0e0",
    "transform" to "scale(1.05)"
))

CSS Variables

Define and use CSS custom properties (CSS variables) for theming and dynamic styling.

Defining Variables

// Define on a container
Box(
    modifier = Modifier()
        .cssVar("primary-color", "#007bff")
        .cssVar("spacing", "16px")
        .cssVar("border-radius", "8px")
) {
    // Children can use these variables
}

// Define multiple variables
Box(
    modifier = Modifier()
        .cssVars(mapOf(
            "primary-color" to "#007bff",
            "secondary-color" to "#6c757d",
            "success-color" to "#28a745"
        ))
)

Using Variables

// Use variables in styles
Box(
    modifier = Modifier()
        .backgroundColor(cssVar("primary-color"))
        .padding(cssVar("spacing"))
        .borderRadius(cssVar("border-radius"))
)

// With fallback values
Box(
    modifier = Modifier()
        .color(cssVar("text-color", "#000000"))
)

Theming Pattern

@Composable
fun ThemedApp() {
    val isDark = remember { mutableStateOf(false) }
    
    val theme = if (isDark.value) {
        mapOf(
            "bg-primary" to "#1a1a1a",
            "text-primary" to "#ffffff",
            "surface" to "#2a2a2a"
        )
    } else {
        mapOf(
            "bg-primary" to "#ffffff",
            "text-primary" to "#000000",
            "surface" to "#f5f5f5"
        )
    }
    
    Box(modifier = Modifier().cssVars(theme)) {
        // All children use theme variables
        Content()
    }
}

Media Queries

Apply responsive styles based on viewport dimensions and device characteristics.

Viewport Breakpoints

// Mobile-first approach
Box(
    modifier = Modifier()
        .padding("8px")
        .mediaQuery(MediaQuery.MinWidth(768)) {
            padding("16px")
        }
        .mediaQuery(MediaQuery.MinWidth(1024)) {
            padding("24px")
        }
)

// Max-width queries
Box(
    modifier = Modifier()
        .display("block")
        .mediaQuery(MediaQuery.MaxWidth(767)) {
            display("none") // Hide on mobile
        }
)

Device Orientation

Box(
    modifier = Modifier()
        .mediaQuery(MediaQuery.Portrait) {
            flexDirection("column")
        }
        .mediaQuery(MediaQuery.Landscape) {
            flexDirection("row")
        }
)

User Preferences

// Dark mode support
Box(
    modifier = Modifier()
        .backgroundColor("#ffffff")
        .color("#000000")
        .mediaQuery(MediaQuery.PrefersDarkScheme) {
            backgroundColor("#1a1a1a")
            color("#ffffff")
        }
)

// Reduced motion
Box(
    modifier = Modifier()
        .transition("all", 300)
        .mediaQuery(MediaQuery.PrefersReducedMotion) {
            transition("none")
        }
)

Device Capabilities

// Hover-capable devices
Box(
    modifier = Modifier()
        .mediaQuery(MediaQuery.CanHover) {
            // Add hover effects only on devices that support it
        }
        .mediaQuery(MediaQuery.NoHover) {
            // Touch-optimized styles
            padding("12px") // Larger touch targets
        }
)

// Pointer precision
Box(
    modifier = Modifier()
        .mediaQuery(MediaQuery.FinePointer) {
            // Mouse/trackpad styles
        }
        .mediaQuery(MediaQuery.CoarsePointer) {
            // Touch styles
            minHeight("44px") // Larger touch targets
        }
)

Common Breakpoints

Use the predefined Breakpoints constants:

import code.yousef.summon.modifier.Breakpoints

Box(
    modifier = Modifier()
        .mediaQuery(MediaQuery.MinWidth(Breakpoints.SM)) { /* Tablet */ }
        .mediaQuery(MediaQuery.MinWidth(Breakpoints.MD)) { /* Desktop */ }
        .mediaQuery(MediaQuery.MinWidth(Breakpoints.LG)) { /* Large desktop */ }
)

Complex Queries

// Combine multiple conditions with AND
modifier.mediaQuery(
    MediaQuery.And(
        MediaQuery.MinWidth(768),
        MediaQuery.MaxWidth(1024),
        MediaQuery.Landscape
    )
) {
    // Styles for tablets in landscape
}

// Multiple conditions with OR
modifier.mediaQuery(
    MediaQuery.Or(
        MediaQuery.MaxWidth(767),
        MediaQuery.Portrait
    )
) {
    // Mobile or any device in portrait
}

Scroll Modifiers

Control scroll behavior and handle scroll events.

Scroll Events

Box(
    modifier = Modifier()
        .height("400px")
        .overflowY("scroll")
        .onScroll("handleScroll(event)")
)

Scroll Behavior

// Smooth scrolling
Box(
    modifier = Modifier()
        .scrollBehavior(ScrollBehavior.SMOOTH)
        .overflowY("auto")
)

Scroll Snapping

// Container with snap points
Box(
    modifier = Modifier()
        .scrollSnapType(ScrollSnapType.Y_MANDATORY)
        .overflowY("scroll")
) {
    // Child elements
    repeat(10) {
        Box(
            modifier = Modifier()
                .scrollSnapAlign(ScrollSnapAlign.START)
                .height("100vh")
        ) {
            Text("Section $it")
        }
    }
}

Overflow Control

// Vertical scrolling only
Modifier().overflowY("auto").overflowX("hidden")

// Horizontal scrolling
Modifier().overflowX("scroll").overflowY("hidden")

// Both directions
Modifier().overflow("auto")

Scroll Margin and Padding

// Scroll margin (space between snap point and viewport)
Modifier().scrollMargin("20px")

// Scroll padding (offset for snap alignment)
Modifier().scrollPadding("20px")

Media Element Modifiers

Special modifiers for Video and Audio elements. These modifiers enable advanced media control behaviors.

Pause on Scroll

Automatically pause media when it scrolls out of view:

Video(
    src = "video.mp4",
    modifier = Modifier()
        .pauseOnScroll()
)

// With custom threshold (percentage of element visible)
Audio(
    src = "audio.mp3", 
    modifier = Modifier()
        .pauseOnScroll(threshold = 0.5) // Pause when less than 50% visible
)

Lazy Loading

Defer media loading until the element approaches the viewport:

// Lazy load with Intersection Observer
Video(
    src = "large-video.mp4",
    modifier = Modifier()
        .lazyLoad() // Default margin: 200px
)

// Custom margin for earlier loading
Video(
    src = "video.mp4",
    modifier = Modifier()
        .lazyLoad(margin = "400px") // Start loading 400px before visible
)

// Native lazy loading (uses browser's loading="lazy")
Image(
    src = "image.jpg",
    modifier = Modifier()
        .nativeLazyLoad()
)

Aspect Ratio

Maintain consistent aspect ratios for media elements:

// 16:9 widescreen
Video(
    src = "video.mp4",
    modifier = Modifier()
        .aspectRatio(16, 9)
)

// 4:3 standard
Video(
    src = "old-video.mp4",
    modifier = Modifier()
        .aspectRatio(4, 3)
)

// 1:1 square (for Instagram-style content)
Video(
    src = "square.mp4",
    modifier = Modifier()
        .aspectRatio(1, 1)
)

Responsive Media

Create fluid, responsive media containers:

// Full-width responsive video
Video(
    src = "video.mp4",
    modifier = Modifier()
        .responsiveMedia()
)

// Responsive with max dimensions
Video(
    src = "video.mp4",
    modifier = Modifier()
        .responsiveMedia(maxWidth = "800px", maxHeight = "600px")
)

Combined Media Modifiers

// Optimized video component
Video(
    src = "hero-video.mp4",
    modifier = Modifier()
        .aspectRatio(16, 9)
        .responsiveMedia(maxWidth = "1200px")
        .lazyLoad(margin = "300px")
        .pauseOnScroll(threshold = 0.25)
        .borderRadius(8.px)
        .boxShadow("0 4px 12px rgba(0,0,0,0.15)")
)

Best Practices

1. Use Type-Safe Enums

// ✅ Preferred
Modifier()
    .display(Display.Flex)
    .justifyContent(JustifyContent.Center)
    .alignItems(AlignItems.Center)

// ❌ Avoid
Modifier()
    .display("flex")
    .justifyContent("center")
    .alignItems("center")

2. Use CSS Unit Extensions

// ✅ Preferred
Modifier()
    .width(200.px)
    .height(100.percent)
    .padding(16.px)
    .fontSize(1.2.rem)

// ❌ Avoid
Modifier()
    .width("200px")
    .height("100%")
    .padding("16px")
    .fontSize("1.2rem")

3. Chain Modifiers Logically

// ✅ Group related properties
Modifier()
    // Layout
    .width(300.px)
    .height(200.px)
    .padding(20.px)
    // Appearance
    .backgroundColor("#f8f9fa")
    .borderRadius(8.px)
    .boxShadow("0 2px 4px rgba(0,0,0,0.1)")
    // Interaction
    .cursor(Cursor.Pointer)
    .hover(Modifier().backgroundColor("#e9ecef"))

4. Use Theme Integration

// ✅ Theme-aware
Modifier()
    .themeBackgroundColor("primary")
    .themeColor("onPrimary")
    .themePadding("md")
    .themeBorderRadius("md")

// ❌ Hardcoded values
Modifier()
    .backgroundColor("#007bff")
    .color("#ffffff")
    .padding("16px")
    .borderRadius("8px")

5. Organize Complex Modifiers

// ✅ Extract complex modifiers
fun cardModifier() = Modifier()
    .backgroundColor("#ffffff")
    .borderRadius(12.px)
    .boxShadow("0 2px 8px rgba(0, 0, 0, 0.1)")
    .transition("all 0.2s ease")
    .hover(
        Modifier()
            .transform("translateY(-2px)")
            .boxShadow("0 4px 12px rgba(0, 0, 0, 0.15)")
    )

// Usage
Card(modifier = cardModifier()) {
    // Card content
}

Migration Notes

When updating from older versions:

  • Replace string-based CSS values with type-safe enums
  • Use CSS unit extensions instead of string literals
  • Update to use new theme integration functions
  • Test interactive states (hover, focus, active)

See Also

On this page
© 2025Yousef
Built withSummonSummon