React styling - EXPRESSO Docs

Every JSX node accepts a style object. Dimensions and spacing use native density-independent units unless a property explicitly accepts a percentage string. Styles apply only to the node where you set them. They do not inherit or cascade to descendants. Set typography, color, spacing, and other values explicitly on each node that needs them. This is also true for registered class styles. text is the inline-text exception for children, not for style inheritance. A text node can contain nested text nodes, and each nested text node can contribute its own inline styling. Nodes such as box, row, column, img, or button nested inside text are ignored as text children; place them beside the text node in a layout container instead. See the text node reference for an example.

Property reference

Colors and backgrounds

Property	Accepted value	Behavior
`backgroundColor`	`string`	Fills the node background. Use a CSS color string such as `"#2563eb"`, `"rgba(0,0,0,0.5)"`, or a named color.
`backgroundGradient`	`string \| Gradient`	Replaces the background color with a CSS-like or structured gradient.
`color`	`string`	Sets the text or foreground color for providers that support color.
`borderColor`	`string`	Sets the border color.

<box
  style={{
    backgroundColor: "#ffffff",
    borderColor: "#e5e7eb",
    borderWidth: 1
  }}
>
  <text style={{ color: "#111827" }}>Card content</text>
</box>

Shape and borders

Property	Accepted value	Behavior
`borderRadius`	`number \| string`	Rounds all corners.
`borderRadiusTopStart`	`number`	Rounds the logical top-start corner.
`borderRadiusTopEnd`	`number`	Rounds the logical top-end corner.
`borderRadiusBottomStart`	`number`	Rounds the logical bottom-start corner.
`borderRadiusBottomEnd`	`number`	Rounds the logical bottom-end corner.
`borderWidth`	`number`	Sets the border width on all sides.
`clip`	`boolean`	Clips child content to the node’s bounds, useful with rounded corners.

Corner names use logical start/end so they work with the app’s layout direction.

Spacing and layout

Property	Accepted value	Behavior
`spacing`	`number`	Adds a gap between direct children in a `row`, `column`, `scrollable`, or `pager`. The gap follows the container’s layout or scroll direction. It does not arrange `box` children.
`padding`	`number`	Sets the same inner spacing on every side.
`paddingStart`	`number`	Sets logical start inner spacing.
`paddingEnd`	`number`	Sets logical end inner spacing.
`paddingTop`	`number`	Sets top inner spacing.
`paddingBottom`	`number`	Sets bottom inner spacing.
`margin`	`number`	Sets the same outer spacing on every side.
`marginStart`	`number`	Sets logical start outer spacing.
`marginEnd`	`number`	Sets logical end outer spacing.
`marginTop`	`number`	Sets top outer spacing.
`marginBottom`	`number`	Sets bottom outer spacing.

For scrollable and pager, prefer padding for edge spacing because margin reduces the usable scroll area.

Size

Property	Accepted value	Behavior
`width`	`number \| string`	Sets the node width. Strings can be percentages such as `"50%"`.
`height`	`number \| string`	Sets the node height. Strings can be percentages such as `"50%"`.
`minWidth`	`number`	Prevents the width from becoming smaller than this value.
`maxWidth`	`number`	Prevents the width from becoming larger than this value.
`minHeight`	`number`	Prevents the height from becoming smaller than this value.
`maxHeight`	`number`	Prevents the height from becoming larger than this value.
`weight`	`number`	Allocates proportional space in a linear parent such as `row` or `column`.
`aspectRatio`	`number`	Maintains width-to-height proportion, for example `1` for a square.

<row style={{ width: "100%", spacing: 12 }}>
  <box style={{ weight: 1, aspectRatio: 1 }} />
  <box style={{ width: 120, height: 80 }} />
</row>

Alignment

Property	Accepted value	Behavior
`horizontalAlignment`	`"start" \| "center" \| "end"`	Positions children horizontally within a layout node.
`verticalAlignment`	`"top" \| "center" \| "bottom"`	Positions children vertically within a layout node.
`textAlignment`	`"start" \| "center" \| "end"`	Aligns text within its available width.

How layout alignment works

horizontalAlignment and verticalAlignment are applied by the parent container to its direct children. They do not change the alignment of descendants deeper in the tree. Set the property on the box, row, or column that owns the children you want to align.

Container behavior

Container	`horizontalAlignment`	`verticalAlignment`	`spacing`
`box`	Aligns every child horizontally inside the box. Children remain stacked.	Aligns every child vertically inside the box.	Not used to arrange children.
`row`	Positions the group of children along the row’s horizontal axis when extra width is available.	Aligns each child on the row’s vertical cross-axis.	Adds a horizontal gap between children.
`column`	Aligns each child on the column’s horizontal cross-axis.	Positions the group of children along the column’s vertical axis when extra height is available.	Adds a vertical gap between children.

The default alignment is start horizontally and top vertically. start and end are logical directions, so they follow the app’s layout direction.

`box`: align overlaid children

box measures its children in the same bounds and uses both alignment properties to place them. This is useful for badges, overlays, and centered empty states.

<box
  style={{
    width: "100%",
    height: 180,
    horizontalAlignment: "center",
    verticalAlignment: "bottom",
    padding: 16,
    backgroundColor: "#dbeafe"
  }}
>
  <img
    src="https://cdn.example.com/hero.jpg"
    alt="Seasonal collection"
    resizeMode="cover"
    style={{ width: "100%", height: "100%" }}
  />
  <text style={{ color: "#ffffff", fontWeight: 700 }}>
    Seasonal collection
  </text>
</box>

The image and text occupy the same box. The text is centered horizontally and placed at the bottom of the box. Render order still controls which child is on top.

`row`: main-axis and cross-axis alignment

For a row, horizontal alignment controls the child group along the row. Vertical alignment controls each child across the row’s height.

<row
  style={{
    width: "100%",
    height: 96,
    horizontalAlignment: "end",
    verticalAlignment: "center",
    spacing: 8,
    padding: 16,
    backgroundColor: "#f2f4f7"
  }}
>
  <text>Subtotal</text>
  <text style={{ fontWeight: 700 }}>€49.00</text>
</row>

The children are grouped at the logical end of the available width and centered vertically. The vertical alignment is visible because the row has more height than its content. Use a child weight to consume remaining horizontal space. Weighted children share that space proportionally; weight has no layout effect on a child inside a box.

<row style={{ width: "100%", spacing: 12 }}>
  <text style={{ weight: 1 }}>Product name</text>
  <button text="Add" onClick={addToCart} />
</row>

`column`: main-axis and cross-axis alignment

For a column, vertical alignment controls the child group along the column. Horizontal alignment controls each child across the column’s width.

<column
  style={{
    width: "100%",
    height: 240,
    horizontalAlignment: "center",
    verticalAlignment: "center",
    spacing: 12,
    padding: 20,
    backgroundColor: "#f9fafb"
  }}
>
  <text style={{ textAlignment: "center", fontWeight: 700 }}>
    Nothing here yet
  </text>
  <button text="Start shopping" onClick={startShopping} />
</column>

The child group is centered vertically and each child is centered horizontally. The column needs extra height for vertical alignment to have visible room to move the group. Use a child weight to consume remaining vertical space:

<column style={{ height: "100%" }}>
  <text>Header</text>
  <box style={{ weight: 1 }} />
  <button text="Continue" />
</column>

Alignment versus text alignment

These properties act at different levels:

Property	Acts on	Example
`horizontalAlignment`	Direct children of `box`, `row`, or `column`	Center a button inside a column.
`verticalAlignment`	Direct children of `box`, `row`, or `column`	Center an icon vertically in a row.
`textAlignment`	Text glyphs inside the text node’s own width	Center a multiline heading.

To center a heading both within its container and within its own width, use the container’s horizontalAlignment: "center" and the text node’s textAlignment: "center".

Spacing, padding, and margin

spacing is a parent layout gap. It is horizontal in a row and vertical in a column.
padding adds space inside the container, so alignment and child layout happen inside the remaining content area.
margin adds space outside the node. It changes the node’s placement in its parent; it does not create a gap between that node’s own children.
On box, spacing does not arrange overlaid children. Use padding, explicit sizes, or a row/column when you need regular gaps.

Alignment only has extra space to distribute when the container is larger than its content. Give a container an explicit or weighted size when you need to see centered or end-aligned content.

Spacing in layout and scrolling nodes

spacing is interpreted by the node that owns the children. It is not a universal margin and it does not add space around the outside edge of a node.

Node	Direction	Effect of `style.spacing`
`row`	Horizontal	Gap between adjacent children. `horizontalAlignment` positions the group when the row has extra width.
`column`	Vertical	Gap between adjacent children. `verticalAlignment` positions the group when the column has extra height.
`scrollable horizontal`	Horizontal	Gap between direct scroll items. `horizontalAlignment` positions items when content is shorter than the viewport.
`scrollable`	Vertical	Gap between direct scroll items. `verticalAlignment` positions items when content is shorter than the viewport.
`pager horizontal`	Horizontal	Gap between pages. This is distance between page bounds, not padding inside a page.
`pager`	Vertical	Gap between pages. This is distance between page bounds, not padding inside a page.
`box`	None	Ignored for child arrangement because children are overlaid.

`row` and `column`

Use spacing on the parent instead of adding margins to every child:

<column style={{ spacing: 16 }}>
  <text>Shipping address</text>
  <text>Payment method</text>
  <button text="Continue" />
</column>

In a row the gap is horizontal. In a column it is vertical. spacing applies between children, not before the first or after the last; use padding for those edges.

`scrollable`

scrollable uses spacing between direct scroll items. Use padding for the viewport and content edges:

<scrollable horizontal style={{ paddingStart: 16, paddingEnd: 16, spacing: 12 }}>
  {products.map((product) => (
    <box key={product.id} style={{ width: 160, height: 220 }}>
      <text>{product.title}</text>
    </box>
  ))}
</scrollable>

For a vertical scrollable, omit horizontal; the same spacing becomes the vertical gap. Do not use margin on the scrollable for leading or trailing edge space because it reduces the usable scroll area. pager uses spacing as the distance between pages, not as an inner gap within each page. Use the page’s own padding for inner content and the pager’s padding for viewport edges:

<pager
  horizontal
  itemSize="84%"
  snapPosition="center"
  style={{ spacing: 12, paddingStart: 16, paddingEnd: 16 }}
>
  {slides.map((slide) => (
    <box key={slide.id} style={{ padding: 16, borderRadius: 16 }}>
      <text>{slide.title}</text>
    </box>
  ))}
</pager>

Typography

Property	Accepted value	Behavior
`fontSize`	`number`	Sets text size.
`fontWeight`	`number`	Sets text weight, for example `400`, `600`, or `700`.
`fontFamily`	`string`	Selects a font family available to the native app.
`textDecoration`	`"none" \| "underline" \| "strikethrough"`	Applies text decoration.
`maxLines`	`number`	Limits the number of rendered text lines.
`minLines`	`number`	Reserves at least this many text lines.

<text
  style={{
    fontSize: 18,
    fontWeight: 700,
    textAlignment: "center",
    maxLines: 2
  }}
>
  Limited-time offer
</text>

Transforms and opacity

Property	Accepted value	Behavior
`alpha`	`number`	Sets opacity from `0` (transparent) to `1` (opaque).
`rotate`	`number`	Rotates the node in degrees.
`scale`	`number`	Sets both horizontal and vertical scale. `1` is the original size.
`scaleX`	`number`	Sets horizontal scale.
`scaleY`	`number`	Sets vertical scale.
`translationX`	`number`	Moves the node horizontally in density-independent units.
`translationY`	`number`	Moves the node vertically in density-independent units.
`transition`	`string`	Present in the style type, but not a reliable interaction-animation contract. Use `gestureDetector` with shared values for pressed or gesture-driven feedback.

Transforms do not change layout measurement; they move or resize the rendered result.

Gradients

Use helpers from @napps/nodes:

import {
  conicGradient,
  linearGradient,
  radialGradient,
  stop
} from "@napps/nodes";

<box
  style={{
    backgroundGradient: linearGradient(90, ["#111827", "#2563eb"])
  }}
/>;

<box
  style={{
    backgroundGradient: radialGradient([
      stop("#ffffff", 0),
      stop("#dbeafe", 1)
    ])
  }}
/>;

Available helpers are linearGradient, radialGradient, sweepGradient, conicGradient, and stop. Structured gradients accept type, angle, centerX, centerY, center, radius, colors, stops, and positions.

Named styles

StyleRegistry stores reusable styles globally within the runtime:

StyleRegistry.registerStyle("promo-title", {
  fontSize: 16,
  fontWeight: 700,
  color: "#111827"
});

<text class="promo-title" style={{ color: "#2563eb" }}>
  Featured
</text>;

Names are global. Prefix them with the component or extension name to avoid collisions. A class applies only to the node where it is declared; it does not cascade.

Interaction feedback

Do not rely on style.transition for pressed or selected interaction feedback. A gesture has a native lifecycle, so use gestureDetector with a shared value when the visual change needs to be reliable or animated. Use React state and a normal style update when the selected state does not need animation.

const scale = sv(1);

<gestureDetector
  gesture="tap"
  onBegin={() => {
    scale.value = timing(0.96, { duration: 80 });
  }}
  onFinalize={() => {
    scale.value = timing(1, { duration: 120 });
  }}
>
  <box style={animatedProps({ scale })}>
    <text>Press me</text>
  </box>
</gestureDetector>;

Keep the detector around the smallest subtree that needs the interaction. Use onFinalize to restore the visual state when the gesture ends or is cancelled.

Styling best practices

Prefer padding over margin for scrollable and pager edge spacing.
Prefer spacing on a parent row or column for consistent child gaps.
Use weight for proportional space in linear layouts.
Use clip when rounded corners should clip child content.
Keep layout values stable and use React state for visual changes.
Do not rely on style.transition for pressed or selected interaction feedback; use gestureDetector with shared values and animatedProps when feedback must animate.

​Property reference

​Colors and backgrounds

​Shape and borders

​Spacing and layout

​Size

​Alignment

​How layout alignment works

​Container behavior

​box: align overlaid children

​row: main-axis and cross-axis alignment

​column: main-axis and cross-axis alignment

​Alignment versus text alignment

​Spacing, padding, and margin

​Spacing in layout and scrolling nodes

​row and column

​scrollable

​pager

​Typography

​Transforms and opacity

​Gradients

​Named styles

​Interaction feedback

​Styling best practices