🎨 Styling

Jaspr gives you a strongly-typed styles system that wraps the most common css properties. You can access these various properties through the Styles class that is exported by the core package.

To pass style attributes to a html component, construct a Styles object and pass it as the styles attribute like this:

div(styles: const Styles.background(color: Colors.red), []);

This will render as:

<div style="background: red"></div>

Style Groups#

Css properties are grouped semantically into style groups that can be accessed through the Styles class as shown above. For example, the background group gives you the set of css properties related to the background style, like color, position or size.

Currently, the following groups exist:

const Styles.background({
  Color? color,
  BackgroundAttachment attachment,
  BackgroundClip? clip,
  ImageStyle? image,
  BackgroundOrigin? origin,
  BackgroundPosition? position,
  BackgroundRepeat? repeat,
  BackgroundSize? size,
})

const Styles.text({
  Color? color,
  TextAlign? align,
  FontFamily? fontFamily,
  FontStyle? fontStyle,
  Unit? fontSize,
  FontWeight? fontWeight,
  TextDecoration? decoration,
  TextTransform? transform,
  Unit? indent,
  Unit? letterSpacing,
  Unit? wordSpacing,
  Unit? lineHeight,
  TextShadow? shadow,
  TextOverflow? overflow,
})

const Styles.box({
  EdgeInsets? padding,
  EdgeInsets? margin,
  Display? display,
  BoxSizing? boxSizing,
  Unit? width,
  Unit? height,
  BoxConstraints? constraints,
  Border? border,
  BorderRadius? radius,
  Outline? outline,
  Overflow? overflow,
  Visibility? visibility, 
  Position? position,
  double? opacity,
  Transform? transform,
  BoxShadow? shadow,
  Cursor? cursor,
  Transition? transition,
})

const Styles.flexbox({
  FlexDirection? direction,
  FlexWrap? wrap,
  JustifyContent? justifyContent,
  AlignItems? alignItems,
})

const Styles.flexItem({
  Flex? flex,
  int? order,
  AlignSelf? alignSelf,
})

const Styles.grid({
  GridTemplate? template,
  GridGap? gap,
  List<TrackSize>? autoRows,
  List<TrackSize>? autoColumns,
})

const Styles.gridItem({
  GridPlacement? placement,
})

Raw Styles#

If you want to work with raw CSS properties or need to use a property that is not supported by the current style groups, use the Styles.raw() method and provide a map of properties and values:

const myStyle = Styles.raw({
  'color': 'blue',
  'some_advanced_css_property': 'special_value',
});

Chaining Styles#

You can chain multiple style group calls like this:

final myStyle = Styles()
  .text(color: Colors.red)
  .background(color: Colors.blue);

Note that this does not produce a constant value. Alternatively you can use the Styles.combine() method to get the same value as a constant:

const myStyle = Styles.combine([
  Styles.text(color: Colors.red),
  Styles.background(color: Colors.blue),
]);

Finally, you can store styles in variables and mix'n'match:

const redText = Styles.text(color: Colors.red);

const redBlueTest = Styles.combine([
  redText,
  Styles.background(color: Colors.blue),
]);

const redGreenTest = Styles.combine([
  redText,
  Styles.background(color: Colors.green),
]);

Style Component#

The Styles class is great for defining a single set of css properties e.g. to be used as inline styles for a single html element.

To define a stylesheet with a set of style rules use the Style (without s) component in combination with the css() method:

Style(styles: [
    css('.red-text').text(color: Colors.red),
    css('#content', [
      css('&').box(width: 100.percent, height: 100.percent),
      css('a').text(color: Colors.green),
    ]),
]);

will render as:

<style>
  #content {
    width: 100%;
    height: 100%;
  }

  #content a {
    color: green;
  }
    
  .red-text {
    color: red;
  }
</style>

The css() method takes a selector and an optional list of children and returns a StyleRule. You can then use the same style group methods on that rule as you can with normal styles.

Nested style rules will be scoped to the parent. Using the & symbol as part of a child selector referst to whatever the parent selected.

There are also additional StyleRule variants that support other css features:

• StyleRule.import(String url) renders a @import url(...) statement.
• StyleRule.media({MediaRuleQuery query, List<StyleRule> styles}) renders a @media ... { ... } statement.
• StyleRule.fontFace({String fontFamily, FontStyle? fontStyle, String url}) renders a @font-face { ... } statement.