Skip to main content

Box

orbital_core_components::layout_box

Function Box 

Source 
pub fn Box(props: BoxProps) -> impl IntoView
Expand description

Generic layout wrapper for spacing, sizing, and surface styling on a single node.

Box is a theme-aware container for one element—like a <div> with optional token-based padding, margin, width, and extra CSS. Use it when a single wrapper needs spacing or sizing without distributing gaps between siblings. foreground sets theme text color — not the CSS color shorthand prop. For even gaps between children, prefer Stack or Flex.

§When to use

  • One wrapper needs padding, margin, max-width, or surface styling - A card-like region without the full Material API - Custom layout chrome where Stack / Flex are too opinionated

§Usage

  1. Put content in the default slot. 2. Set typed padding, margin, background, radius, and related token props. 3. Pass additional rules through style when you need escape-hatch CSS. 4. Add utility classes through class when needed.

§Best Practices

§Do’s

§Don’ts

  • Do not use Box to space multiple siblings — prefer Stack or Flex * Avoid hard-coded hex colors; use ThemeColor tokens

§Examples

§Default

A bordered box with sample text—the quickest way to see the container bounds.

use crate::Box;
use orbital_base_components::{BorderRadius, SpacingInset, StrokeWidth, ThemeColor};
view! {
    <div data-testid="box-preview">
        <Box
            padding=SpacingInset::all_m()
            background=ThemeColor::NeutralBackground1
            foreground=ThemeColor::NeutralForeground1
            border_color=ThemeColor::NeutralStroke1
            radius=BorderRadius::Medium
            border_style="dashed"
            border_width=StrokeWidth::Thin
        >
            "This Box wraps content with theme-aware spacing and stroke tokens."
        </Box>
    </div>
}

§Padding

The padding prop adds inner space without extra wrapper markup.

use crate::Box;
use orbital_base_components::{BorderRadius, SpacingInset, StrokeWidth, ThemeColor};
view! {
    <div data-testid="box-padding">
        <Box
            padding=SpacingInset::all_l()
            foreground=ThemeColor::NeutralForeground1
            border_color=ThemeColor::NeutralStroke1
            radius=BorderRadius::Medium
            border_style="dashed"
            border_width=StrokeWidth::Thin
        >
            "Extra padding keeps content away from the dashed border."
        </Box>
    </div>
}

§Margin

The margin prop offsets the box from surrounding layout—visible against a tinted backdrop.

use crate::Box;
use orbital_base_components::{BorderRadius, SpacingInset, StrokeWidth, ThemeColor};
view! {
    <div data-testid="box-margin" style="padding: var(--orb-space-inline-sm); background: var(--orb-color-surface-subtle); border-radius: var(--orb-radius-md);">
        <Box
            margin=SpacingInset::all_l()
            padding=SpacingInset::all_m()
            foreground=ThemeColor::NeutralForeground1
            border_color=ThemeColor::NeutralStroke1
            radius=BorderRadius::Medium
            border_style="dashed"
            border_width=StrokeWidth::Thin
        >
            "Margin pushes this box away from the outer frame."
        </Box>
    </div>
}

§Width

Constrain width on forms, side panels, and compact callouts.

use crate::Box;
use orbital_base_components::{BorderRadius, SpacingInset, StrokeWidth, ThemeColor};
view! {
    <div data-testid="box-width">
        <Box
            width="280px"
            padding=SpacingInset::all_m()
            foreground=ThemeColor::NeutralForeground1
            border_color=ThemeColor::NeutralStroke1
            radius=BorderRadius::Medium
            border_style="dashed"
            border_width=StrokeWidth::Thin
        >
            "A fixed width keeps this callout readable in wide layouts."
        </Box>
    </div>
}

§Surface styling

Combine typed surface props for a subtle raised panel.

use crate::Box;
use orbital_base_components::{BorderRadius, Shadow, SpacingInset, StrokeWidth, ThemeColor};
view! {
    <div data-testid="box-surface">
        <Box
            padding=SpacingInset::all_l()
            background=ThemeColor::NeutralBackground1
            foreground=ThemeColor::NeutralForeground1
            border_color=ThemeColor::NeutralStroke1
            radius=BorderRadius::Medium
            border_width=StrokeWidth::Thin
            shadow=Shadow::Shadow4
        >
            "Surface tokens give the box a resting elevation on the page canvas."
        </Box>
    </div>
}

§Optional Props