Macro silkenweb::css

css!() { /* proc-macro */ }

Define &str constants for each class in a CSS file.

This defines 2 modules:

• mod class with constants or functions (depending on auto_mount) for each CSS class. For a CSS class called my-css-class, a constant called MY_CSS_CLASS or a function called my_css_class will be defined.
• mod stylesheet with:
  • An fn text() -> &'static str that gets the content of the stylesheet.
  • fn mount() and fn mount_dom<D: Document>() that lazily call DefaultDom::mount_in_head or D:mount_in_head once, respectively. This ensures the stylesheet is in the head. Any subsequent calls to either function will have no effect.

The macro takes two forms. Firstly it can take a single string literal which is the path to the CSS/SCSS/SASS file. The path is relative to the $CARGO_MANIFEST_DIR environment variable.

Alternatively, named parameters can be specified.

Parameters

Parameters take the form:

css!(
    path = "my-css-file.css",
    syntax = "css",
    prefix = "prefix",
    include_prefixes = ["included-"],
    exclude_prefixes = ["excluded-"],
    auto_mount,
    validate,
    transpile = (
        minify,
        pretty,
        modules,
        nesting,
        browsers = (
            android = (1, 0, 0),
            chrome = (1, 0, 0),
            edge = (1, 0, 0),
            firefox = (1, 0, 0),
            ie = (1, 0, 0),
            ios_saf = (1, 0, 0),
            opera = (1, 0, 0),
            safari = (1, 0, 0),
            samsung = (1, 0, 0),
        )
    )
);

All are optional, but one of path or content must be specified.

• path is the path to the CSS/SCSS/SASS file. The syntax is determined from the extension.
• syntax explicitly specifies the syntax. It must be one of “css”, “scss”, or “sass”. The default is “css”. It overrides any syntax inferred from path.
• content is the css content.
• prefix: only classes starting with prefix should be included. Their Rust names will have the prefix stripped.
• include_prefixes: a list of prefixes to include, without stripping the prefix. Rust constants will only be defined for classes starting with one or more of these prefixes.
• exclude_prefixes: a list of prefixes to exclude. No Rust constants will be defined for a class starting with any of these prefixes. exclude_prefixes takes precedence over include_prefixes.
• auto_mount: Generate a function for each CSS class that will call stylesheet::mount before returning the class name.
• validate: validate the CSS. Requires crate feature css-transpile.
• transpile: transpile the CSS with lightningcss. Requires crate feature css-transpile.

transpile

• minify: Minify the CSS returned by stylesheet(). Minification also adds/removes vendor prefixes, so it’s a good idea to keep this the same between debug and release builds. Use pretty if you want legible CSS in debug.
• pretty: Pretty print the final output. This is the default unless minify is specified.
• modules: Enable CSS Modules to locally scope class identifiers, via lightningcss. Composition is unsupported.
• nesting: Allow CSS nesting.
• browsers is a comma seperated list of the minimum supported browser versions. This will add vendor prefixes to the CSS from stylesheet(). The version is a paranthesized , seperated string of major, minor, and patch versions. For example, to support firefox 110 + and chrome 111+, use browsers =( firefox = (110, 0, 0), chrome = (111, 0, 0) ).

Examples

Define private constants for all CSS classes:

css!("my-css-file.css");
assert_eq!(class::MY_CLASS, "my-class");

Define private constants for all content CSS classes:

css!(content = r#"
   .my-class {
       color: hotpink;
   }
"#);
assert_eq!(class::MY_CLASS, "my-class");
assert_eq!(stylesheet::text(), r#"
   .my-class {
       color: hotpink;
   }
"#);

Include classes starting with border-, except classes starting with border-excluded-:

css!(
    path = "my-css-file.css",
    prefix = "border-",
    exclude_prefixes = ["border-excluded-"]
);

assert_eq!(class::SMALL, "border-small");

This won’t compile because exclude_prefixes takes precedence over include_prefixes:

css!(
    path = "my-css-file.css",
    include_prefixes = ["border-"]
    exclude_prefixes = ["border-excluded-"]
);

assert_eq!(class::BORDER_EXCLUDED_HUGE, "border-excluded-huge");