Module lightningcss::properties
source · Expand description
CSS property values.
Each property provides parsing and serialization support using the Parse and ToCss traits. Properties are fully parsed as defined by the CSS spec, and printed in their canonical form. For example, most CSS properties are case-insensitive, and may be written in various orders, but when printed they are lower cased as appropriate and in a standard order.
CSS properties often also contain many implicit values that are automatically filled in during parsing when omitted. These are also omitted when possible during serialization. Many properties also implement the Default trait, which returns the initial value for the property.
Shorthand properties are represented as structs containing fields for each of the sub-properties. If some of the sub-properties are not specified in the shorthand, their default values are filled in.
The Property enum contains the values of all properties, and can be used to parse property values by name. The PropertyId enum represents only property names, and not values and is used to refer to known properties.
Example
This example shows how the background
shorthand property is parsed and serialized. The parse_string
function parses the background into a structure with all missing fields filled in with their default values.
When printed using the to_css_string
function, the components are in their canonical order, and default
values are removed.
use smallvec::smallvec;
use lightningcss::{
properties::{Property, PropertyId, background::*},
values::{url::Url, image::Image, color::CssColor, position::*, length::*},
stylesheet::{ParserOptions, PrinterOptions},
dependencies::Location,
};
let background = Property::parse_string(
PropertyId::from("background"),
"url('img.png') repeat fixed 20px 10px / 50px 100px",
ParserOptions::default()
).unwrap();
assert_eq!(
background,
Property::Background(smallvec![Background {
image: Image::Url(Url {
url: "img.png".into(),
loc: Location { line: 1, column: 1 }
}),
color: CssColor::RGBA(cssparser::RGBA {
red: 0,
green: 0,
blue: 0,
alpha: 0
}),
position: BackgroundPosition {
x: HorizontalPosition::Length(LengthPercentage::px(20.0)),
y: VerticalPosition::Length(LengthPercentage::px(10.0)),
},
repeat: BackgroundRepeat {
x: BackgroundRepeatKeyword::Repeat,
y: BackgroundRepeatKeyword::Repeat,
},
size: BackgroundSize::Explicit {
width: LengthPercentageOrAuto::LengthPercentage(LengthPercentage::px(50.0)),
height: LengthPercentageOrAuto::LengthPercentage(LengthPercentage::px(100.0)),
},
attachment: BackgroundAttachment::Fixed,
origin: BackgroundOrigin::PaddingBox,
clip: BackgroundClip::BorderBox,
}])
);
assert_eq!(
background.to_css_string(false, PrinterOptions::default()).unwrap(),
r#"background: url("img.png") 20px 10px / 50px 100px fixed"#
);
If you have a cssparser::Parser already, you can also use the parse
and to_css
methods instead, rather than parsing from a string.
Unparsed and custom properties
Custom and unknown properties are represented by the CustomProperty struct, and the
Property::Custom
variant. The value of these properties is not parsed, and is stored as a raw
TokenList, with the name as a string.
If a known property is unable to be parsed, e.g. it contains var()
references, then it is represented by the
UnparsedProperty struct, and the Property::Unparsed
variant. The value is stored
as a raw TokenList, with a PropertyId as the name.