The style class

The style class, ol.style.Style, contains the drawing instructions to be used when rendering a feature. There are five properties we can use when creating a style property:

Name	Type	Description
`fill`	`ol.style.Fill`	This style is used when filling polygons. To draw unfilled polygons, leave this property out or set to `null`.
`stroke`	`ol.style.Stroke`	This style is used when drawing lines and drawing the outline of polygons. To draw polygons without an outline, leave this property out or set to `null`.
`image`	`ol.style.Image`	This style is used when drawing points.
`text`	`ol.style.Text`	This style is used when drawing text.
`zIndex`	`number`	The z-index determines the order in which features are drawn. To ensure that certain features are drawn on top of other features—for instance, points on top of polygons—assign a higher `zIndex` value. Note that this only affects features within the same layer.

As you can see, a style is really a composite of several specific types. Including a property turns on drawing of the relevant type and excluding it turns it off. When you specify the style property for a vector layer, this replaces all the default styles; so, you don't need to override all the properties all the time—just specify the ones that are needed and the rest will not be drawn at all. For example, creating a style with just a stroke property will draw polygons with an outline and no fill:

var style = new ol.style.Style({
  stroke: new ol.style.Stroke({
    color: [127,127,127,1]
  })
});

Now, let's look at each specific property type with some examples.

Fill styles

The fill style—ol.style.Fill—is used to fill shapes with a solid color. The fill style is used by ol.style.Style as well as a couple of other objects we'll see shortly. It has a single property, color, of the type ol.Color that is used when drawing filled shapes.

Note

Colors may be specified in three ways:

An array of four values representing the red, green, blue, and alpha components of the color. The color components are numbers between 0 and 255, while the alpha value is between 0 (transparent) and 1 (opaque). For example, black is represented as [0,0,0,1], white is represented as [255,255,255,1], and a semitransparent blue green is [0,255,0,0.5].
A CSS RGBA string expression, written as "rgba(red,green,blue,alpha)", where red, green, blue, and alpha are the same as the preceding array form; for example, our semitransparent green color will be "rgba(0,255,0,0.5)".
A CSS hexadecimal, or hex, color value written as #RRGGBB, where RR is the red value, GG is the green value, and BB is the blue value. The values are a hexadecimal equivalent of the numeric values between 0 and 255, written as 00 to FF. The alpha value is assumed to be 1 in this case.

These different representations are equivalent (except for the missing alpha control in hex colors) and you can use whichever is more convenient.

Stroke styles

The stroke style— ol.style.Stroke—is used to draw lines. The line style is used by ol.style.Style as well as a couple of other objects we'll see shortly. A stroke style has the following options.

Name	Type	Description
`color`	`ol.Color`	This is the color to use when drawing lines.
`lineCap`	`string`	This is the style to draw the end of lines in. This may be one of the following: `butt`: These finish lines squarely right at the exact point the line ends at. `round`: These finish lines by rounding them, radius depends on `width` at the bottom. This is the default value if not specified. `square`: These finish lines with a square the size of `width` (line extends past the last point by the line width) See the diagram following this table for an example of each `lineCap` style.
`lineJoin`	`string`	The line join style is used when drawing segments that are part of the same line. This may be one of the following: `bevel`: This joins lines with a bevel. `round`: This joins lines by rounding them. This is the default value if not specified. `miter`: This joins lines by mitering them (see `miterLimit` below). See the diagram following this table for an example of each `lineJoin` style.
`lineDash`	`Array.<number>`	This is an array of numbers that define the on-off pattern for drawing lines with a dash pattern. The default is none (no dash pattern).
`miterLimit`	`number`	This is the limit for drawing miter joins; the default is 10.
`width`	`number`	This is the width, in pixels, to draw the line. This number may be a floating point number.

The following diagram illustrates the effect of the various values for lineJoin (top) and lineCap (bottom).

Have a Go Hero – fill and stroke styles

Modify the last example and try out some fill and stroke style properties. In particular, try changing the lineJoin and lineCap properties. Use a wider stroke width to see the effect it produces. Note that the lineCap style won't be apparent when drawing polygons—to see it in action, you'll need a line layer, perhaps, using the fells_loop.gpx file we saw in the previous chapter.

Here are a couple of examples:

var countryStyle = new ol.style.Style({
  fill: new ol.style.Fill({
    color: [0, 255, 255, 1]
  }),
  stroke: new ol.style.Stroke({
    color: [127,127,127,1.0],
    width: 10,
    lineJoin: 'bevel',
  })
});
var timezoneStyle = new ol.style.Style({
  stroke: new ol.style.Stroke({
    color: [64, 200, 200, 0.5],
    lineJoin: 'round',
    width: 10
  })
});

Image styles

The image style—ol.style.Image—is used to style point data. You won't be using it directly though. Instead, there are two subclasses that you'll be using: ol.style.Icon and ol.style.Circle. Let's look at the icon style first.

The icon style

The icon style displays an image at the location of a point. There are quite a few properties associated with the icon style that allow you to align the placement of the image relative to the precise geographic location being represented.

Name	Type	Description
`anchor`	`Array.<number>`	This property states where to position the image relative to the geographic location of the point specified as an array of two numbers. The default value is `[0.5, 0.5]` and assumes units of `fraction` (see `anchorXUnits` and `anchorYUnits`). This will specify aligning the center of the image to the geographic location. The position within the image is measured relative to the `anchorOrigin` property, which defaults to `top-left`.
`anchorOrigin`	`string`	This specifies where the anchor value is measured from. One of the following values can be used: `top-left` (the default) `top-right` `bottom-left` `bottom-right`
`anchorXUnits`	`string`	This specifies the units of the X `anchor` value, either `pixels` or `fraction`. The default value is `fraction`. When `fraction` is used, the value of the associated value is a floating point number between 0 and 1 as a percentage of the width or height of the image.
`anchorYUnits`	`string`	This specifies the units of the Y `anchor` value.
`crossOrigin`	`string`	The `crossOrigin` setting for the image allows you to leverage CORS (Cross Origin Resource Sharing) when loading an image.
`img`	`Image`	This is an image object to use for the icon. This may be used instead of the `src` property but the provided image object must already be loaded.
`offset`	`Array.<number>`	This is the top-left corner of the image to draw the icon from. When combined with the `size` property, this would allow you to use an image sprite and selecting a portion of the sprite to display for a specific icon. The default is `[0,0]`.
`offsetOrigin`	`String`	This sets the origin of the `offset` property, one of the following: `bottom-left` `bottom-right` `top-left` (the default) `top-right`
`scale`	`number`	This is a scale factor to use when drawing the image, the default is 1 (do not scale the image). A value of 2 will double the size of the icon and a value of 0.5 will half the size of the icon.
`snapToPixel`	`Boolean`	If `true`, this property will cause images to be snapped to integer pixel values and result in sharper display of images. If `false`, the image will be placed more accurately but may appear blurry. The default value is `true`. You may want to set this to `false` if you are animating an icon's position, as snapping to pixels would cause noticeable jitter.
`rotateWithView`	`Boolean`	If `true`, the icon will rotate when the map's view is rotated. The default is `false` (always stay upright).
`rotation`	`number`	This is a rotation (in radians) to apply to the icon.
`size`	`ol.Size`	This is the size of the icon in pixels as an array of two values—`width` and `height`. The default value is the size of the image being used. Using a different value, when combined with `origin`, allows the use of image sprites.
`src`	`string`	This is the URL to load the image from.

The following diagram illustrates the meaning of the origin, size, and anchor options:

Previous Chapter

Time for action – basic styling

Next Chapter

Time for action – using the icon style

Table of Contents for OpenLayers 3 : Beginner's Guide