Expand description
§leptos-css
[!IMPORTANT]
leptos-csshas been renamed totyped-css. This is the finalleptos-cssrelease and receives no further updates.typed-cssis the same library under a framework-neutral name, with its Leptos integration behind theleptosfeature:[dependencies] typed-css = { version = "0.2", features = ["leptos"] }To migrate, change your imports from
leptos_css::...totyped_css::....typed-css0.2 also redesigns the API and adds many properties. Its changelog lists every change sinceleptos-css0.1.The documentation below describes
leptos-css0.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 fallibletry_*counterparts for runtime-derived values. Helpers return the narrowest modeled grammar, sorgb()andhsl()feed every selector acceptingCssColordirectly. - Typed arithmetic and typed
css_min(),css_max(),css_clamp(), andcss_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
PropertyNamecatalog with kebab-caseas_str()output; it is neither a declaration API nor a complete CSS property index
§Installation
cargo add leptos-cssleptos-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 fallibletry_*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, soautoand directly negative values work only where CSS permits. - Ordinary property selectors accept CSS-wide keywords through
declare_global().AllPropertyaccepts only a CSS-wide keyword. - Public enums are
#[non_exhaustive]. Downstream matches must include a wildcard arm.
§License
Dual licensed under either of:
- MIT License (LICENSE-MIT)
- Apache License, Version 2.0 (LICENSE-APACHE)
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§
- Checked
Declaration - An owned CSS declaration whose property and value grammar were checked together.
- CssCustom
Property - A validated CSS custom property associated with one Rust value grammar.
- CssDimension
Expr - A typed CSS length-percentage expression.
- CssVariable
Reference - A typed
var()reference with a mandatory, grammar-matching fallback. - Declaration
Value - A checked literal or a typed custom-property reference for one CSS grammar.
- Finite
F64 - A finite IEEE-754 double used by typed CSS numeric values.
- Invalid
Custom Property Name - Error returned when a custom-property name is outside the checked identifier subset.
- Invalid
View Transition Name - Error returned when a view-transition name is not in the checked
<custom-ident>subset. - Length
Percentage Calculation - A length-percentage math expression suitable for a property grammar.
- NonNegative
Finite F64 - A finite, non-negative number used by CSS grammars with a lower bound of zero.
- NonNegative
Length Percentage - A non-negative
<length-percentage>suitable for grammars such aspaddingandgap. - Opacity
- A normalized opacity value in the inclusive range
0..=1. - Percentage
Channel - A finite percentage channel in the inclusive range
0..=100. - Touch
Action Gestures - A non-empty composition of panning and pinch-zoom gestures for
touch-action. - Unit
Interval - A finite number in the inclusive range
0..=1. - View
Transition Name - A checked
view-transition-namevalue.
Enums§
- Border
Corner Radius - A logical or physical corner-radius longhand value.
- CssAngle
- CSS angle values.
- CssColor
- CSS color values from CSS Color Level 4.
- CssColor
Name - CSS named-color keywords supported by the typed API.
- CssDimension
- A CSS
<length-percentage>value. - CssEnvironment
Variable - 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.
- Font
Weight - CSS font-weight values.
- Forced
Color Adjust - Values for the modern
forced-color-adjustproperty. - Gap
- A checked
gapshorthand value. - GapValue
- One component of the
gap,row-gap, orcolumn-gapgrammar. - Global
Keyword - CSS-wide keywords accepted by ordinary CSS properties.
- Inset
- CSS
insetshorthand values. - Inset
Axis - Values for the
inset-blockandinset-inlineshorthands. - Invalid
CssNumber - Error returned when a floating-point value cannot be represented by a typed CSS value.
- Invalid
NonNegative Length Percentage - Error returned when a dimension is not a non-negative
<length-percentage>. - Length
Percentage Auto - A
<length-percentage> | autovalue for grammars such as margin and inset offsets. - Margin
- CSS margin shorthand values.
- Margin
Axis - Values for the
margin-blockandmargin-inlineshorthands. - MaxSize
- Values supported by the typed maximum-size property APIs.
- NonNegative
Length Percentage Value - A direct or calculated
<length-percentage [0,∞]>value. - Padding
- CSS padding shorthand values.
- Padding
Axis - Values for the
padding-blockandpadding-inlineshorthands. - Print
Color Adjust - Values for the modern
print-color-adjustproperty. - Size
- Values supported by the typed
width,height, and minimum-size property APIs. - Touch
Action - A standards-valid
touch-actionvalue. - Touch
Action Horizontal Pan - A horizontal panning component of the
touch-actiongrammar. - Touch
Action Vertical Pan - A vertical panning component of the
touch-actiongrammar. - ZIndex
- A typed
z-indexvalue.
Traits§
- Checked
CssValue - A crate-validated CSS value grammar eligible for checked declarations.
- CssWrite
To - Open serialization trait for CSS-like values.
Functions§
- ch
- Create a CSS ch (character width) value — the width of the
0glyph 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
chvalue. - try_cqh
- Attempt to create a finite CSS
cqhvalue. - try_cqw
- Attempt to create a finite CSS
cqwvalue. - try_deg
- Attempt to create a finite CSS degree angle.
- try_dvh
- Attempt to create a finite CSS
dvhvalue. - try_dvw
- Attempt to create a finite CSS
dvwvalue. - try_em
- Attempt to create a finite CSS
emvalue. - 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
lvhvalue. - try_lvw
- Attempt to create a finite CSS
lvwvalue. - 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
pxvalue. - try_rad
- Attempt to create a finite CSS radian angle.
- try_rem
- Attempt to create a finite CSS
remvalue. - 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
svhvalue. - try_svw
- Attempt to create a finite CSS
svwvalue. - try_
turn - Attempt to create a finite CSS turn angle.
- try_vh
- Attempt to create a finite CSS
vhvalue. - try_
vmax - Attempt to create a finite CSS
vmaxvalue. - try_
vmin - Attempt to create a finite CSS
vminvalue. - try_vw
- Attempt to create a finite CSS
vwvalue. - 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).