# Module: ol/style/flat

This documentation is for OpenLayers v10.9.0. The latest is v.

## ol/style/flat

Vector layers can be styled with an object literal containing properties for stroke, fill, image, and text styles. The types below can be composed into a single object. For example, a style with both stroke and fill properties could look like this:

    const style = {
      'stroke-color': 'yellow',
      'stroke-width': 1.5,
      'fill-color': 'orange',
    };

See details about the available properties depending on what type of symbolizer should be applied: `Stroke` - properties for applying a stroke to lines and polygons `Fill` - properties for filling polygons `Text` - properties for labeling points, lines, and polygons `Icon` - properties for rendering points with an icon `Circle` - properties for rendering points with a circle `Shape` - properties for rendering points with a regular shape

To conditionally apply styles based on a filter, a list of `rules` can be used. For example, to style points with a big orange circle if the population is greater than 1 million and a smaller blue circle otherwise:

    const rules = [
      {
        filter: ['>', ['get', 'population'], 1_000_000],
        style: {
          'circle-radius': 10,
          'circle-fill-color': 'red',
        }
      },
      {
        else: true,
        style: {
          'circle-radius': 5,
          'circle-fill-color': 'blue',
        },
      },
    ];

### Type Definitions

#### BooleanExpression{boolean} {Array}

  A literal boolean (e.g. `true`) or an expression that evaluates to a boolean (e.g. `['>', ['get', 'population'], 1_000_000]`).

#### ColorExpression{Color} {string} {Array}

  A CSS named color (e.g. `'blue'`), an array of 3 RGB values (e.g. `[0, 255, 0]`), an array of 4 RGBA values (e.g. `[0, 255, 0, 0.5]`), or an expression that evaluates to one of these color types (e.g. `['get', 'color']`).

#### DefaultStyle{Object}

  These default style properties are applied when no other style is given.

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `fill-color` | string | `'rgba(255,255,255,0.4)'`
  `stroke-color` | string | `'#3399CC'`
  `stroke-width` | number | `1.25`
  `circle-radius` | number | `5`
  `circle-fill-color` | string | `'rgba(255,255,255,0.4)'`
  `circle-stroke-width` | number | `1.25`
  `circle-stroke-color` | string | `'#3399CC'`

#### FlatCircle{Object}

  Circle style properties for rendering point features. At least `circle-radius` must be provided.

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `circle-radius` | NumberExpression | undefined | Circle radius.
  `circle-fill-color` | ColorExpression | undefined | The fill color. `'none'` means no fill and no hit detection.
  `circle-stroke-color` | ColorExpression | undefined | The stroke color.
  `circle-stroke-width` | NumberExpression | undefined | Stroke pixel width.
  `circle-stroke-line-cap` | StringExpression (defaults to 'round') | Line cap style: `butt`, `round`, or `square`. (Canvas only)
  `circle-stroke-line-join` | StringExpression (defaults to 'round') | Line join style: `bevel`, `round`, or `miter`. (Canvas only)
  `circle-stroke-line-dash` | NumberArrayExpression | undefined | Line dash pattern. (Canvas only)
  `circle-stroke-line-dash-offset` | NumberExpression (defaults to 0) | Line dash offset. (Canvas only)
  `circle-stroke-miter-limit` | NumberExpression (defaults to 10) | Miter limit. (Canvas only)
  `circle-displacement` | NumberArrayExpression (defaults to [0,0]) | displacement
  `circle-scale` | SizeExpression (defaults to 1) | Scale. A two-dimensional scale will produce an ellipse. Unless two-dimensional scaling is required a better result may be obtained with an appropriate setting for `circle-radius`.
  `circle-opacity` | NumberExpression | undefined | Circle opacity. (WebGL only)
  `circle-rotation` | NumberExpression (defaults to 0) | Rotation in radians (positive rotation clockwise, meaningful only when used in conjunction with a two-dimensional scale).
  `circle-rotate-with-view` | BooleanExpression (defaults to false) | Whether to rotate the shape with the view (Expression only supported in Canvas) (meaningful only when used in conjunction with a two-dimensional scale).
  `circle-declutter-mode` | DeclutterMode | undefined | Declutter mode (Canvas only)
  `z-index` | NumberExpression | undefined | The zIndex of the style. (Canvas only)

#### FlatFill{Object}

  Fill style properties applied to polygon features.

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `fill-color` | ColorExpression | undefined | The fill color. `'none'` means no fill and no hit detection (applies to Canvas only).
  `fill-pattern-src` | StringExpression | undefined | Fill pattern image source URI. If `fill-color` is defined as well, it will be used to tint this image. (Expressions only in Canvas)
  `fill-pattern-size` | SizeExpression | undefined | Fill pattern image size in pixels. Can be used together with `fill-pattern-offset` to define the sub-rectangle to use from a fill pattern image sprite sheet.
  `fill-pattern-offset` | SizeExpression (defaults to [0, 0]) | Offset, which, together with the size and the offset origin, define the sub-rectangle to use from the original fill pattern image.
  `fill-pattern-offset-origin` | IconOrigin (defaults to 'top-left') | Origin of the offset: `bottom-left`, `bottom-right`, `top-left` or `top-right`. (WebGL only)

#### FlatIcon{Object}

  Icon style properties applied to point features. `icon-src` must be provided to render points with an icon.

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `icon-src` | string | undefined | Image source URI.
  `icon-anchor` | NumberArrayExpression (defaults to [0.5, 0.5]) | Anchor. Default value is the icon center.
  `icon-anchor-origin` | IconOrigin (defaults to 'top-left') | Origin of the anchor: `bottom-left`, `bottom-right`, `top-left` or `top-right`.
  `icon-anchor-x-units` | IconAnchorUnits (defaults to 'fraction') | Units in which the anchor x value is specified. A value of `'fraction'` indicates the x value is a fraction of the icon. A value of `'pixels'` indicates the x value in pixels.
  `icon-anchor-y-units` | IconAnchorUnits (defaults to 'fraction') | Units in which the anchor y value is specified. A value of `'fraction'` indicates the y value is a fraction of the icon. A value of `'pixels'` indicates the y value in pixels.
  `icon-color` | ColorExpression | undefined | Color to tint the icon. If not specified, the icon will be left as is.
  `icon-cross-origin` | null | string | undefined | The `crossOrigin` attribute for loaded images. Note that you must provide a `icon-cross-origin` value if you want to access pixel data with the Canvas renderer. See https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_enabled_image for more detail.
  `icon-offset` | SizeExpression (defaults to [0, 0]) | Offset, which, together with the size and the offset origin, define the sub-rectangle to use from the original icon image.
  `icon-displacement` | NumberArrayExpression (defaults to [0,0]) | Displacement of the icon.
  `icon-offset-origin` | IconOrigin (defaults to 'top-left') | Origin of the offset: `bottom-left`, `bottom-right`, `top-left` or `top-right`.
  `icon-opacity` | NumberExpression (defaults to 1) | Opacity of the icon.
  `icon-scale` | SizeExpression (defaults to 1) | Scale.
  `icon-width` | NumberExpression | undefined | Width of the icon. If not specified, the actual image width will be used. Cannot be combined with `scale`. (Expressions only in WebGL)
  `icon-height` | NumberExpression | undefined | Height of the icon. If not specified, the actual image height will be used. Cannot be combined with `scale`. (Expressions only in WebGL)
  `icon-rotation` | NumberExpression (defaults to 0) | Rotation in radians (positive rotation clockwise).
  `icon-rotate-with-view` | BooleanExpression (defaults to false) | Whether to rotate the icon with the view. (Expressions only supported in Canvas)
  `icon-size` | SizeExpression | undefined | Icon size in pixel. Can be used together with `icon-offset` to define the sub-rectangle to use from the origin (sprite) icon image. (Expressions only in WebGL)
  `icon-declutter-mode` | DeclutterMode | undefined | Declutter mode (Canvas only)
  `z-index` | NumberExpression | undefined | The zIndex of the style. (Canvas only)

#### FlatShape{Object}

  Regular shape style properties for rendering point features. At least `shape-points` must be provided.

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `shape-points` | NumberExpression | undefined | Number of points for stars and regular polygons. In case of a polygon, the number of points is the number of sides. (Expressions only in WebGL)
  `shape-fill-color` | ColorExpression | undefined | The fill color. `'none'` means no fill and no hit detection.
  `shape-stroke-color` | ColorExpression | undefined | The stroke color.
  `shape-stroke-width` | NumberExpression | undefined | Stroke pixel width.
  `shape-stroke-line-cap` | StringExpression (defaults to 'round') | Line cap style: `butt`, `round`, or `square`. (Canvas only)
  `shape-stroke-line-join` | StringExpression (defaults to 'round') | Line join style: `bevel`, `round`, or `miter`. (Canvas only)
  `shape-stroke-line-dash` | NumberArrayExpression | undefined | Line dash pattern. (Canvas only)
  `shape-stroke-line-dash-offset` | NumberExpression (defaults to 0) | Line dash offset. (Canvas only)
  `shape-stroke-miter-limit` | NumberExpression (defaults to 10) | Miter limit. (Canvas only)
  `shape-radius` | NumberExpression | undefined | Radius of a regular polygon. (Expressions only in WebGL)
  `shape-radius2` | NumberExpression | undefined | Second radius to make a star instead of a regular polygon. (Expressions only in WebGL)
  `shape-angle` | NumberExpression (defaults to 0) | Shape's angle in radians. A value of 0 will have one of the shape's point facing up. (Expressions only in WebGL)
  `shape-displacement` | NumberArrayExpression (defaults to [0,0]) | Displacement of the shape
  `shape-opacity` | NumberExpression | undefined | Shape opacity. (WebGL only)
  `shape-rotation` | NumberExpression (defaults to 0) | Rotation in radians (positive rotation clockwise).
  `shape-rotate-with-view` | BooleanExpression (defaults to false) | Whether to rotate the shape with the view. (Expression only supported in Canvas)
  `shape-scale` | SizeExpression (defaults to 1) | Scale. Unless two-dimensional scaling is required a better result may be obtained with appropriate settings for `shape-radius` and `shape-radius2`.
  `shape-declutter-mode` | DeclutterMode | undefined | Declutter mode. (Canvas only)
  `z-index` | NumberExpression | undefined | The zIndex of the style. (Canvas only)

#### FlatStroke{Object}

  Stroke style properties applied to line strings and polygon boundaries. To apply a stroke, at least one of `stroke-color` or `stroke-width` must be provided.

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `stroke-color` | ColorExpression | undefined | The stroke color.
  `stroke-width` | NumberExpression | undefined | Stroke pixel width.
  `stroke-line-cap` | StringExpression (defaults to 'round') | Line cap style: `butt`, `round`, or `square`.
  `stroke-line-join` | StringExpression (defaults to 'round') | Line join style: `bevel`, `round`, or `miter`.
  `stroke-line-dash` | NumberArrayExpression | undefined | Line dash pattern.
  `stroke-line-dash-offset` | NumberExpression (defaults to 0) | Line dash offset.
  `stroke-miter-limit` | NumberExpression (defaults to 10) | Miter limit.
  `stroke-offset` | NumberExpression | undefined | Stroke offset in pixel along the normal. A positive value offsets the line to the right, relative to the direction of the line.
  `stroke-pattern-src` | string | undefined | Stroke pattern image source URI. If `stroke-color` is defined as well, it will be used to tint this image. (WebGL only)
  `stroke-pattern-offset` | SizeExpression (defaults to [0, 0]) | Offset, which, together with the size and the offset origin, define the sub-rectangle to use from the original stroke pattern image. (WebGL only)
  `stroke-pattern-offset-origin` | IconOrigin (defaults to 'top-left') | Origin of the offset: `bottom-left`, `bottom-right`, `top-left` or `top-right`. (WebGL only)
  `stroke-pattern-size` | SizeExpression | undefined | Stroke pattern image size in pixel. Can be used together with `stroke-pattern-offset` to define the sub-rectangle to use from the origin (sprite) fill pattern image. (WebGL only)
  `stroke-pattern-spacing` | NumberExpression | undefined | Spacing between each pattern occurrence in pixels; 0 if undefined. (WebGL only)
  `stroke-pattern-start-offset` | NumberExpression | undefined | Stroke pattern offset in pixels at the start of the line. (WebGL only)
  `z-index` | NumberExpression | undefined | The zIndex of the style.

#### FlatStyle{FlatFill} {FlatStroke} {FlatText} {FlatIcon} {FlatShape} {FlatCircle}

  For static styling, the `layer.setStyle()` method can be called with an object literal that has fill, stroke, text, icon, regular shape, and/or circle properties.

#### FlatStyleLike{FlatStyle} {Array<FlatStyle>} {Array<Rule>}

  A flat style literal or an array of the same.

#### FlatText{Object}

  Label style properties applied to all features. At a minimum, a `text-value` must be provided. Note: text style is currently not supported in WebGL layers

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `text-value` | StringExpression | undefined | Text content (with `\n` for line breaks).
  `text-font` | StringExpression (defaults to '10px sans-serif') | Font style as CSS `font` value.
  `text-max-angle` | NumberExpression (defaults to Math.PI/4) | When `text-placement` is set to `'line'`, allow a maximum angle between adjacent characters. The expected value is in radians, and the default is 45° (`Math.PI / 4`).
  `text-offset-x` | NumberExpression (defaults to 0) | Horizontal text offset in pixels. A positive will shift the text right.
  `text-offset-y` | NumberExpression (defaults to 0) | Vertical text offset in pixels. A positive will shift the text down.
  `text-overflow` | BooleanExpression (defaults to false) | For polygon labels or when `placement` is set to `'line'`, allow text to exceed the width of the polygon at the label position or the length of the path that it follows.
  `text-placement` | StringExpression (defaults to 'point') | Text placement.
  `text-repeat` | NumberExpression | undefined | Repeat interval in pixels. When set, the text will be repeated at this interval. Only available when `text-placement` is set to `'line'`. Overrides `text-align`.
  `text-scale` | SizeExpression | undefined | Scale.
  `text-rotate-with-view` | BooleanExpression (defaults to false) | Whether to rotate the text with the view.
  `text-rotation` | NumberExpression (defaults to 0) | Rotation in radians (positive rotation clockwise).
  `text-align` | StringExpression | undefined | Text alignment. Possible values: `'left'`, `'right'`, `'center'`, `'end'` or `'start'`. Default is `'center'` for `'text-placement': 'point'`. For `'text-placement': 'line'`, the default is to let the renderer choose a placement where `text-max-angle` is not exceeded.
  `text-justify` | StringExpression | undefined | Text justification within the text box. If not set, text is justified towards the `textAlign` anchor. Otherwise, use options `'left'`, `'center'`, or `'right'` to justify the text within the text box. Note: `text-justify` is ignored for immediate rendering and also for `'text-placement': 'line'`.
  `text-baseline` | StringExpression (defaults to 'middle') | Text base line. Possible values: `'bottom'`, `'top'`, `'middle'`, `'alphabetic'`, `'hanging'`, `'ideographic'`.
  `text-padding` | NumberArrayExpression (defaults to [0, 0, 0, 0]) | Padding in pixels around the text for decluttering and background. The order of values in the array is `[top, right, bottom, left]`.
  `text-fill-color` | ColorExpression | undefined | The fill color. `'none'` means no fill and no hit detection.
  `text-background-fill-color` | ColorExpression | undefined | The fill color. `'none'` means no fill and no hit detection.
  `text-stroke-color` | ColorExpression | undefined | The stroke color.
  `text-stroke-line-cap` | StringExpression (defaults to 'round') | Line cap style: `butt`, `round`, or `square`.
  `text-stroke-line-join` | StringExpression (defaults to 'round') | Line join style: `bevel`, `round`, or `miter`.
  `text-stroke-line-dash` | NumberArrayExpression | undefined | Line dash pattern.
  `text-stroke-line-dash-offset` | NumberExpression (defaults to 0) | Line dash offset.
  `text-stroke-miter-limit` | NumberExpression (defaults to 10) | Miter limit.
  `text-stroke-width` | NumberExpression | undefined | Stroke pixel width.
  `text-background-stroke-color` | ColorExpression | undefined | The stroke color.
  `text-background-stroke-line-cap` | StringExpression (defaults to 'round') | Line cap style: `butt`, `round`, or `square`.
  `text-background-stroke-line-join` | StringExpression (defaults to 'round') | Line join style: `bevel`, `round`, or `miter`.
  `text-background-stroke-line-dash` | NumberArrayExpression | undefined | Line dash pattern.
  `text-background-stroke-line-dash-offset` | NumberExpression (defaults to 0) | Line dash offset.
  `text-background-stroke-miter-limit` | NumberExpression (defaults to 10) | Miter limit.
  `text-background-stroke-width` | NumberExpression | undefined | Stroke pixel width.
  `text-declutter-mode` | DeclutterMode | undefined | Declutter mode
  `z-index` | NumberExpression | undefined | The zIndex of the style.

#### NumberArrayExpression{Array.<number>} {Array}

  An array of numbers (e.g. `[1, 2, 3]`) or an expression that evaluates to the same (e.g. `['get', 'values']`).

#### NumberExpression{number} {Array}

  A literal number (e.g. `42`) or an expression that evaluates to a number (e.g. `['+', 40, 2]`).

#### Rule{Object}

  A rule is used to conditionally apply a style. If the rule's filter evaluates to true, the style will be applied.

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `style` | FlatStyle | Array<FlatStyle> | The style to be applied if the filter matches.
  `filter` | EncodedExpression | undefined | The filter used to determine if a style applies. If no filter is included, the rule always applies (unless it is an else rule).
  `else` | boolean | undefined | If true, the rule applies only if no other previous rule applies. If the else rule also has a filter, the rule will not apply if the filter does not match.

#### SizeExpression{number} {Array.<number>} {Array}

  An array of two numbers (e.g. `[10, 20]`) or an expression that evaluates to the same (e.g. `['get', 'size']`).

#### StringExpression{string} {Array}

  A literal string (e.g. `'hello'`) or an expression that evaluates to a string (e.g. `['get', 'greeting']`).

#### StyleVariables{Object.<string, (number|Array.<number>|string|boolean)>}

  Style variables are provided as an object. The variables can be read in a `style expression` using the `['var', 'varName']` operator. Each variable must hold a literal value (not an expression).