StaticContainer

Updated: Sep 24, 2026
Use StaticContainer for non-interactive content that needs a ContainerMaterial backdrop and shape clipping. The toolkit owns material rendering and clipping; the caller chooses the visual state and provides the content. Unlike Container, StaticContainer has no focus, press, tab index, content-scale motion, or interaction-state transitions.
Typical uses include a status pill, a legibility backing behind text over media, or a grouped block of read-only content. Chip, Tag, TooltipContainer, and ContextMenu use this foundation behavior.

Usage

import {StaticContainer, TextView, TextStyle} from '@wearables-ui-toolkit/mrbd';

function ServiceNotice() {
  return (
    <StaticContainer>
      <TextView className="notice-body" textStyle={TextStyle.BODY1}>
        Service resumes after the scheduled inspection.
      </TextView>
    </StaticContainer>
  );
}
.notice-body {
  padding: var(--uit-spacing-large);
}
Set BackgroundStyle.NONE when the application needs shape clipping without a visible material:
import {BackgroundStyle, StaticContainer} from '@wearables-ui-toolkit/mrbd';

<StaticContainer backgroundStyle={BackgroundStyle.NONE}>
  <img className="clipped-media" src={posterUrl} alt="" />
</StaticContainer>;
When content changes the intrinsic size, request a coordinated transition so the toolkit moves the box, material bounds, and content clip together:
import {StaticContainer, TextView, TextStyle} from '@wearables-ui-toolkit/mrbd';
import {useEffect, useState} from 'react';

function StatusPill({status}: {status: string}) {
  const [transitionToken, setTransitionToken] = useState(0);

  useEffect(() => {
    setTransitionToken(token => token + 1);
  }, [status]);

  return (
    <StaticContainer
      layoutTransitionToken={transitionToken}
      layoutTransitionAnchor="start"
    >
      <TextView className="status-pill" textStyle={TextStyle.META1}>
        {status}
      </TextView>
    </StaticContainer>
  );
}

Props

StaticContainer renders a div, accepts standard div attributes such as className, style, id, role, aria-*, data-*, and DOM event handlers, and forwards unrecognized props and its ref to that root. The full prop type is StaticContainerProps.
The toolkit owns the root’s position, size, border radius, and overflow. Express size and shape with width, height, and shapeProvider; values for those properties in style are overwritten so material geometry and clipping remain consistent.
PropTypeDefaultDescription
children
ReactNode
—
Content stacked above background layers and below foreground layers.
material
ContainerMaterial
the default static material
Material to render. When backgroundStyle is SECONDARY, that style supplies its own material and takes precedence. A material instance can be mounted by only one container at a time.
shapeProvider
ShapeProvider
rounded rectangle at the large corner radius
Geometry for content clipping and every material fill and stroke path.
backgroundStyle
BackgroundStyle
BackgroundStyle.PRIMARY
Selects the primary or secondary static material, or hides the material.
visualState
VisualState
VisualState.DEFAULT
Static visual state rendered by the material. It adds no interaction behavior.
width
number \| string
'auto'
CSS width. A number is treated as pixels. When both width and height are numbers, the toolkit computes the shape path without waiting for measurement.
height
number \| string
'auto'
CSS height, with the same rules as width.
clipContent
boolean
true
Clips the content subtree to the shape. It does not clip material layers.
useSmoothCorners
boolean
true
When false, uses a plain CSS border radius instead of the shape provider’s smooth path.
contentClassName
string
''
Additional class for the content wrapper when the outer className already handles layout.
layoutTransitionToken
number
0
Increment to request one coordinated layout transition.
layoutTransitionSignature
unknown
—
Value that describes the current intrinsic content. An identity change requests a coordinated layout transition, so pass a primitive or stable object rather than a new literal on every render.
layoutTransitionAnchor
'start' \| 'end'
'start'
Edge that remains fixed while the box resizes during a layout transition.
onLayoutTransitionComplete
() => void
—
Runs when a requested layout transition finishes, including when the toolkit skips it.

Types and enums

BackgroundStyle

MemberValueBehavior
BackgroundStyle.NONE
'none'
Holds the material at VisualState.NONE, so nothing is drawn. Shape, clipping, and layout still apply, and a passed material is retained rather than replaced.
BackgroundStyle.PRIMARY
'primary'
Uses the primary static material, or the material prop when supplied.
BackgroundStyle.SECONDARY
'secondary'
Uses the secondary static material as a quieter backdrop over an existing surface. This takes precedence over material.
visualState accepts a VisualState value.

Behavior

  • No interaction.StaticContainer has no tab index, focus or press handling, activation, or content-scale animation. Use Container when a composition needs interaction so the toolkit can provide consistent focus, press, and keyboard behavior.
  • Fixed visual state. The toolkit holds the material at visualState until that prop changes. BackgroundStyle.NONE always resolves to VisualState.NONE, regardless of visualState, and hides the material.
  • Hidden material is not rendered. The toolkit removes material layers from the tree when the resolved state is NONE or the material is hidden or fully transparent, rather than rendering invisible layers.
  • Material opacity stays on the material. The toolkit multiplies the material’s own alpha and per-state alpha on the layer wrappers, never on the root. A translucent backdrop therefore leaves content at its authored opacity.
  • Smooth corners need a size. The toolkit generates the smooth path after it knows the size from numeric width and height props or measurement. Auto-sized content receives the same measured path for its clip and material. Until the size is known, and whenever useSmoothCorners is false, the toolkit uses the shape provider’s plain CSS border radius.
  • Geometry uses the untransformed box. The toolkit derives material paths and canvas sizes from the border box, so a StaticContainer inside a scaled ancestor still draws its material at full size.
  • Material insets. When a material declares an inset, the toolkit places its layers inside the element box and regenerates their path at the smaller size.
  • Clipping and stacking.clipContent clips only the caller’s content subtree, allowing material overflow such as a glow stroke or drop shadow to remain visible. The root establishes a stacking context so background layers paint behind content and foreground layers paint above it. If the material declares backdrop blending, the root instead opens that context and receives data-uit-background-blends-with-backdrop.
  • Layout transitions. Intrinsic content changes would otherwise snap the box and material to a new size. Increment layoutTransitionToken or change layoutTransitionSignature to ask the toolkit to animate the size, material bounds, material canvases, and content clip on one clock. layoutTransitionAnchor selects the fixed edge, and onLayoutTransitionComplete runs at the end. The toolkit skips a transition when start and end sizes match and clears any remaining transition geometry. It also skips transitions when the user prefers reduced motion.
  • Content sizing. The root is an inline flex box and hugs its content by default. The content wrapper fills the box when width or height is explicit and hugs its content when both remain 'auto'.

Accessibility

StaticContainer is a visual wrapper and adds no role or accessible name. It renders a plain div and forwards caller-provided ARIA and data attributes, so values such as role="status", aria-label, or aria-hidden="true" for a purely decorative backdrop reach the root. The application owns the content’s semantics. Avoid labeling the wrapper as a control because it has no control behavior.
StaticContainer is not focusable and never participates in directional navigation. If a region must be reachable, place a real control inside an otherwise supported composition or use Container so focus and activation have a clear owner.
  • Inset authored, non-full-bleed content with var(--uit-spacing-large), and let full-bleed media use the component’s clipping.
  • Use BackgroundStyle.NONE when the application needs shape and clipping without a visible backdrop.
  • Give every mounted container its own material instance and keep it stable with useMemo. Immutable shape providers can be shared.
  • Increment layoutTransitionToken when an application-owned content change resizes the box, so the toolkit can keep material and clip geometry synchronized.
  • Keep an inset rounded child concentric with its owner by choosing the corner-radius token equal to the owner’s radius minus the inset token.

Unsupported compositions

  • Do not nest Container, StaticContainer, Surface, Button, Chip, Tag, or Header inside a StaticContainer. These components each own surface or interaction behavior, so nesting produces an unsupported composition.
  • Prefer the corresponding component or ordinary text hierarchy instead of stretching one short label, count, or status across a full-width rounded StaticContainer to imitate a Tag, Chip, Header, or Button.
  • Avoid another rounded surface around text that already sits on a static material; one surface owner keeps the hierarchy clear.
  • Do not add click handlers to imitate an interactive surface. StaticContainer has no focus, press, or keyboard support; use Container for an accessible interaction target.
  • Do not reconstruct an unsupported variant of an existing component from foundation primitives. Treat that need as a library gap so behavior and accessibility remain consistent.