Skip to main content

Crate leptos_css

Crate leptos_css 

Source
Expand description

§leptos-css

crates.io docs.rs CI MSRV

[!IMPORTANT] leptos-css has been renamed to typed-css. This is the final leptos-css release and receives no further updates. typed-css is the same library under a framework-neutral name, with its Leptos integration behind the leptos feature:

[dependencies]
typed-css = { version = "0.2", features = ["leptos"] }

To migrate, change your imports from leptos_css::... to typed_css::.... typed-css 0.2 also redesigns the API and adds many properties. Its changelog lists every change since leptos-css 0.1.

The documentation below describes leptos-css 0.1.

Typed CSS primitives and property-specific declaration grammars for Leptos. The checked API is deliberately fail-closed: unsupported CSS cannot be smuggled in as an arbitrary value string, and a value can become a declaration only through a selector for a property whose grammar it satisfies.

leptos-css is the typed foundation of the leptos-styles family. Its checked boundary is the owned CheckedDeclaration returned by a property selector. Integrations can store and pass that concrete type without separating its checked property/value pairing.

Applications can use handwritten CSS or Leptos string styles for declarations outside the checked API.

§Features

  • Closed value types for lengths, percentages, colors, angles, times, global keywords, and selected property grammars
  • Constructor helpers (px, pct, em, rem, vh, vw, deg, rgb, hsl, …) with finite-input validation, plus fallible try_* counterparts for runtime-derived values. Helpers return the narrowest modeled grammar, so rgb() and hsl() feed every selector accepting CssColor directly.
  • Typed arithmetic and typed css_min(), css_max(), css_clamp(), and css_env() constructors; function bodies are expression trees rather than strings
  • Validated, grammar-typed custom properties and var() references with mandatory typed fallbacks
  • Property selectors for checked Leptos declarations, including padding, margin, inset, sizing and radius properties, colors, opacity, color adjustment, view transitions, font weight, touch action, and z-index
  • A curated, non-exhaustive PropertyName catalog with kebab-case as_str() output; it is neither a declaration API nor a complete CSS property index

§Installation

cargo add leptos-css

leptos-css is compatible with Leptos 0.8 and requires Rust 1.89 or newer.

Enable the nightly feature when the application also enables leptos/nightly:

cargo add leptos-css --features nightly

§Example

use leptos::prelude::{ElementChild, StyleAttribute, view};
use leptos_css::{
    CssColor, CssColorName, CssWriteTo, LengthPercentageCalculation, Padding, Size, TouchAction,
    TouchActionGestures, TouchActionHorizontalPan, TouchActionVerticalPan, css_custom_property, pct,
    px, rgb, try_px, var,
    property::{ColorProperty, PaddingProperty, TouchActionProperty, WidthProperty},
};

css_custom_property!(ACCENT_COLOR: CssColor = "--accent-color");

let mut buf = String::new();
px(16).write_to(&mut buf);
assert_eq!(buf, "16px");

let measured_width = try_px(24.5).expect("24.5 is a finite CSS length");
assert_eq!(measured_width.to_string(), "24.5px");

let padding = Padding::all(px(16));
assert_eq!(padding.to_string(), "16px");
let padding_declaration = PaddingProperty.declare(padding);
let _view = view! {
    <div style=padding_declaration>"Typed padding"</div>
};
let _rgb_declaration = ColorProperty.declare(rgb(12, 34, 56));

let width = Size::Calculation(LengthPercentageCalculation::new(pct(100) - px(20)));
assert_eq!(width.to_string(), "calc(100% - 20px)");
let _width_declaration = WidthProperty.declare(width);

let touch_gestures = TouchActionGestures::horizontal(TouchActionHorizontalPan::PanX)
    .with_vertical(TouchActionVerticalPan::PanY)
    .with_pinch_zoom();
let _touch_declaration = TouchActionProperty.declare(TouchAction::Gestures(touch_gestures));

let _accent_declaration = ACCENT_COLOR.declare(CssColor::Named(CssColorName::Aqua));
let _color_declaration = ColorProperty.declare(var(
    &ACCENT_COLOR,
    CssColor::Named(CssColorName::CurrentColor),
));

§Usage notes

  • Convenience constructors (px, pct, deg, s, hsl, …) panic on invalid input. Use their fallible try_* counterparts for runtime-derived values.
  • Property selectors enforce their CSS grammars. Margin and inset accept LengthPercentageAuto, while padding and gap accept non-negative length-percentage values, so auto and directly negative values work only where CSS permits.
  • Ordinary property selectors accept CSS-wide keywords through declare_global(). AllProperty accepts only a CSS-wide keyword.
  • Public enums are #[non_exhaustive]. Downstream matches must include a wildcard arm.

§License

Dual licensed under either of:

at your option.

Re-exports§

pub use property::PropertyName;

Modules§

property
Canonical property names and grammar-checked declaration selectors. CSS property-name catalog and grammar-checked selectors.

Macros§

css_custom_property
Declare a reusable, statically named typed CSS custom property.

Structs§

CheckedDeclaration
An owned CSS declaration whose property and value grammar were checked together.
CssCustomProperty
A validated CSS custom property associated with one Rust value grammar.
CssDimensionExpr
A typed CSS length-percentage expression.
CssVariableReference
A typed var() reference with a mandatory, grammar-matching fallback.
DeclarationValue
A checked literal or a typed custom-property reference for one CSS grammar.
FiniteF64
A finite IEEE-754 double used by typed CSS numeric values.
InvalidCustomPropertyName
Error returned when a custom-property name is outside the checked identifier subset.
InvalidViewTransitionName
Error returned when a view-transition name is not in the checked <custom-ident> subset.
LengthPercentageCalculation
A length-percentage math expression suitable for a property grammar.
NonNegativeFiniteF64
A finite, non-negative number used by CSS grammars with a lower bound of zero.
NonNegativeLengthPercentage
A non-negative <length-percentage> suitable for grammars such as padding and gap.
Opacity
A normalized opacity value in the inclusive range 0..=1.
PercentageChannel
A finite percentage channel in the inclusive range 0..=100.
TouchActionGestures
A non-empty composition of panning and pinch-zoom gestures for touch-action.
UnitInterval
A finite number in the inclusive range 0..=1.
ViewTransitionName
A checked view-transition-name value.

Enums§

BorderCornerRadius
A logical or physical corner-radius longhand value.
CssAngle
CSS angle values.
CssColor
CSS color values from CSS Color Level 4.
CssColorName
CSS named-color keywords supported by the typed API.
CssDimension
A CSS <length-percentage> value.
CssEnvironmentVariable
User-agent environment variables supported by the typed env() expression.
CssLength
CSS length values with absolute and relative units.
CssTime
CSS time values.
CssValue
A closed union of typed CSS component values.
FontWeight
CSS font-weight values.
ForcedColorAdjust
Values for the modern forced-color-adjust property.
Gap
A checked gap shorthand value.
GapValue
One component of the gap, row-gap, or column-gap grammar.
GlobalKeyword
CSS-wide keywords accepted by ordinary CSS properties.
Inset
CSS inset shorthand values.
InsetAxis
Values for the inset-block and inset-inline shorthands.
InvalidCssNumber
Error returned when a floating-point value cannot be represented by a typed CSS value.
InvalidNonNegativeLengthPercentage
Error returned when a dimension is not a non-negative <length-percentage>.
LengthPercentageAuto
A <length-percentage> | auto value for grammars such as margin and inset offsets.
Margin
CSS margin shorthand values.
MarginAxis
Values for the margin-block and margin-inline shorthands.
MaxSize
Values supported by the typed maximum-size property APIs.
NonNegativeLengthPercentageValue
A direct or calculated <length-percentage [0,∞]> value.
Padding
CSS padding shorthand values.
PaddingAxis
Values for the padding-block and padding-inline shorthands.
PrintColorAdjust
Values for the modern print-color-adjust property.
Size
Values supported by the typed width, height, and minimum-size property APIs.
TouchAction
A standards-valid touch-action value.
TouchActionHorizontalPan
A horizontal panning component of the touch-action grammar.
TouchActionVerticalPan
A vertical panning component of the touch-action grammar.
ZIndex
A typed z-index value.

Traits§

CheckedCssValue
A crate-validated CSS value grammar eligible for checked declarations.
CssWriteTo
Open serialization trait for CSS-like values.

Functions§

ch
Create a CSS ch (character width) value — the width of the 0 glyph in the element’s font.
cqh
Create a CSS container query height value (1cqh = 1% of the nearest size container’s height).
cqw
Create a CSS container query width value (1cqw = 1% of the nearest size container’s width).
css_clamp
Create a typed CSS clamp(min, preferred, max) length-percentage expression.
css_env
Create a typed CSS env() expression for a supported user-agent variable.
css_max
Create a typed CSS max() length-percentage expression.
css_min
Create a typed CSS min() length-percentage expression.
deg
Create a CSS degree angle value.
dvh
Create a CSS dynamic viewport height value. Unlike vh, adjusts when browser UI elements (e.g. mobile address bar) appear or disappear.
dvw
Create a CSS dynamic viewport width value. Unlike vw, adjusts when browser UI elements (e.g. mobile address bar) appear or disappear.
em
Create a CSS em value (relative to the element’s font size).
fr
Create a CSS fractional unit value (for CSS Grid).
grad
Create a CSS gradian angle value.
hsl
Create a CSS HSL color value.
hsla
Create a CSS HSLA color value with alpha.
lvh
Create a CSS large viewport height value. Represents the viewport height when all dynamic browser UI is retracted/hidden.
lvw
Create a CSS large viewport width value. Represents the viewport width when all dynamic browser UI is retracted/hidden.
ms
Create a CSS milliseconds time value.
number
Create a bare CSS number.
pct
Create a CSS percentage value.
px
Create a CSS pixel value.
rad
Create a CSS radian angle value.
rem
Create a CSS rem value (relative to the root element’s font size).
rgb
Create a CSS RGB color value.
rgba
Create a CSS RGBA color value with alpha.
s
Create a CSS seconds time value.
svh
Create a CSS small viewport height value. Represents the viewport height when all dynamic browser UI is expanded/visible.
svw
Create a CSS small viewport width value. Represents the viewport width when all dynamic browser UI is expanded/visible.
try_ch
Attempt to create a finite CSS ch value.
try_cqh
Attempt to create a finite CSS cqh value.
try_cqw
Attempt to create a finite CSS cqw value.
try_deg
Attempt to create a finite CSS degree angle.
try_dvh
Attempt to create a finite CSS dvh value.
try_dvw
Attempt to create a finite CSS dvw value.
try_em
Attempt to create a finite CSS em value.
try_fr
Attempt to create a finite, non-negative CSS fractional unit value.
try_grad
Attempt to create a finite CSS gradian angle.
try_hsl
Attempt to create a CSS HSL color value.
try_hsla
Attempt to create a CSS HSLA color value.
try_lvh
Attempt to create a finite CSS lvh value.
try_lvw
Attempt to create a finite CSS lvw value.
try_ms
Attempt to create a finite CSS milliseconds value.
try_number
Attempt to create a finite bare CSS number.
try_pct
Attempt to create a finite CSS percentage value.
try_px
Attempt to create a finite CSS px value.
try_rad
Attempt to create a finite CSS radian angle.
try_rem
Attempt to create a finite CSS rem value.
try_rgba
Attempt to create a CSS RGBA color value with alpha.
try_s
Attempt to create a finite CSS seconds value.
try_svh
Attempt to create a finite CSS svh value.
try_svw
Attempt to create a finite CSS svw value.
try_turn
Attempt to create a finite CSS turn angle.
try_vh
Attempt to create a finite CSS vh value.
try_vmax
Attempt to create a finite CSS vmax value.
try_vmin
Attempt to create a finite CSS vmin value.
try_vw
Attempt to create a finite CSS vw value.
turn
Create a CSS turn angle value.
var
Reference a typed custom property using a mandatory fallback of the same grammar.
vh
Create a CSS viewport-height value (1vh = 1% of the viewport height).
vmax
Create a CSS vmax value (1vmax = 1% of the larger viewport dimension).
vmin
Create a CSS vmin value (1vmin = 1% of the smaller viewport dimension).
vw
Create a CSS viewport-width value (1vw = 1% of the viewport width).