Colours, gradients and patterns

Skip to:

This page describes how to override the default colour list with your own selection of colours, gradients and pattern fills. The same colour formats are used for specifying how to fill the background areas of legends, tooltips, the grid area and the whole graph background area.

From version 3.4 SVGGraph also supports the use of gradients and patterns for stroking lines.

The colour list

In earlier versions of SVGGraph the default colours used for bars, pie slices and markers were picked at random from the list of named colours that SVG supports. In version 2.10, a new default colour scheme was added to make graphs more usable without having to choose your own.

The colours used may be overridden from the default set by passing an array of SVGGraph colour types to the colours() function:

$colours = array(
  'red',
  'green',
  '#00ffff',
  'rgb(100,200,100)',
  array('red','green'),
  array('blue', 'pattern' => 'spot'),
);

$graph->colours($colours);

The colours are assigned to each bar, pie slice or data set (for graphs that show multiple sets of data) in order from the array, repeating when the number of items to show is greater than the number of entries in the array.

The different types of entry that can be used in the array are described in the colours, gradients and patterns sections of this page.

Colour set and range functions

The colours function specifies a single list of colours, patterns and gradients to be used for the graph. The new colour functions added in version 2.17 allow for specifying different colour arrays or ranges of colours for each dataset on a multi-dataset graph.

Colour set and range functions

View source

This example shows a stacked bar graph with five datasets. The first four datasets each have their colours specified using one of the colour functions, as shown in the code fragment below:

$colours = array(
  'red',
  '#0f0',
  array('red', 'blue'),
  array('green', 'white', 'h'),
  array('blue', 'white:0.1', 'blue'),
  array('red', 'pattern' => 'polkadot'),
  array('green', 'pattern' => 'line', 'angle' => 45),
  'blue'
);

$graph->colourSet(0, $colours);
$graph->colourRangeHexRGB(1, '#f00', '#00f');
$graph->colourRangeHexHSL(2, '#f00', '#00f');
$graph->colourRangeHexHSL(3, '#f00', '#00f', true);

The first dataset in the example (dataset 0, the one at the bottom) uses the colourSet function to set a list of colours. There are solid colours, gradients and patterns included in the set. Because there are more bars on the graph than entries in the list, the colours start to repeat. The different types of colour entry are described in the sections after this.

Dataset 1 uses the colourRangeHexRGB function to specify an RGB colour range. The start and end colours are set to #f00 and #00f, and the colours in between are chosen as though there were a straight line drawn between the two ends of the range in the RGB colour cube. The number of colours in the range is dependent on the number of entries in the graph.

Dataset 2 uses colourRangeHexHSL to specify an HSL colour range. The RGB values of each end of the range are converted to hue, saturation and lightness values, and then these are interpolated to find the colours in between. The difference between two hues on the colour wheel is an angle - by default, the HSL colour range functions will use the smallest angle between the two ends of the range (≤180°). For dataset 3, the optional $reverse argument to colourRangeHexHSL is set to true, which makes it choose the greater angle between the two hues (≥180°).

Finally, dataset 4 at the top of the graph does not have any colours set, so the first colour set is repeated.

For this example I've only used the colourRangeHexHSL and colourRangeHexRGB functions with their simple RGB hex code syntax. Here is how the other functions could be used to create the same ranges:

$graph->colourRangeRGB(1, 255, 0, 0, 0, 0, 255);      // #f00 -> #00f
$graph->colourRangeRGBtoHSL(2, 255, 0, 0, 0, 0, 255);
$graph->colourRangeHSL(3, 0, 1, 0.5, 240, 1, 0.5, true);

All of these colour functions (and some others) are listed on the function reference page.

Colours

To specify a single solid colour you may use any of the standard named colours, or 6-dgit hex, 3-digit hex, RGB, RGBA, HSL and HSLA formats:

$red = 'red';             // named colour
$red = '#ff0000';         // 6-digit hex notation
$red = '#f00';            // 3-digit hex notation
$red = 'rgb(255,0,0)';    // RGB colour
$red = 'hsl(0,100%,50%)'; // HSL colour

Note: RGBA and HSLA colours can be used for transparency, though SVGGraph has a number of _opacity options that use the SVG “opacity” attribute for this. Mixing the two might cause problems, or it might give you exactly the effect you want.

Special colours

Apart from the standard colours that are normal in HTML and CSS, there are a few other values that are specific to SVG and SVGGraph.

"none" - this is the value that SVG uses to specify when something is not drawn, e.g. <rect fill="none"> would draw a rectangle that is not filled in. SVGGraph can use this value to skip drawing parts of the graph document.

"fillColour" - this is a fake colour name that tells you want to draw something in the main colour of the related data item. An example is setting the stroke_colour option to fillColour to draw the edge around bar graph bars in the same colour as the bar is filled.

"fill" - this is similar to the fillColour colour name, but allows using the whole of the data item's filling, which could be a gradient or pattern as well as a solid colour.

Opacity

SVGGraph supports appending an opacity value to the colour using a colon as separator:

$red = 'red:0.25'; // 25% opacity
$red = '#f00:0.5'; // 50% opacity

The value will be split out and used for the opacity attribute where it is appropriate, or ignored in places where it would not be useful.

Filters

Version 3.5 of SVGGraph introduced support for colour filters, functions that change the colour in some way. They are added to the end of the colour string, after the opacity value if you have one, and separated by slashes:

$colour1 = 'red/saturation(50%)'; // red, but less red
$colour2 = 'red/brightness(0.5)'; // red, less bright
$colour3 = 'red/hue(120)';        // not red at all
$colour4 = 'red:0.5/brightness';  // red, brighter, semi-transparent

// an adjusted purple colour
$colour4 = '#ff00ff/saturation(-10%)/hue(-10)/brightness(+0.2)';

// whatever the fill colour is, but less bright
$colour5 = 'fillColour/brightness(60%)';

I'm not going to try to explain what saturation, brightness and hue are - there is a really long HSL and HSV Wikipedia page for that.

All of the example graphs below work on the colour #b04040, which is the dull, drab pink one marked “no filter”. I've chosen this colour because its saturation and brightness are somewhere in the middle and can therefore be both increased and decreased.

saturation

The saturation function takes an optional argument which can be either a percentage or a decimal value and acts on the 's' component of the colour when converted to HSL:

$colour1 = "yellow/saturation";        // default value 0.0, desaturates colour
$colour2 = "yellow/saturation(50%)";   // s * 50%
$colour3 = "yellow/saturation(0.5)";   // s * 0.5 (the same as 50%)
$colour4 = "yellow/saturation(+10%)";  // s + 10%
$colour5 = "yellow/saturation(-10%)";  // s - 10%
$colour6 = "yellow/saturation(+0.1)";  // s + 0.1 (the same as +10%)
$colour7 = "yellow/saturation(-0.1)";  // s - 0.1 (the same as -10%)

Values with leading + or - symbols increase or decrease the saturation by the given amount, values without a leading symbol are multiplied. To fully saturate a colour, use a value of +100% or +1.

Saturation filters

View source

Brightness

The brightness function takes an optional argument in the same way as the saturation function - a percentage or decimal value. The function acts on the 'l' component of the HSL colour, which stands for 'lightness':

$colour1 = "orange/brightness";        // default value 1.2, 20% brighter
$colour2 = "orange/brightness(50%)";   // l * 50%
$colour3 = "orange/brightness(0.5)";   // l * 0.5 (the same as 50%)
$colour4 = "orange/brightness(+10%)";  // l + 10%
$colour5 = "orange/brightness(-10%)";  // l - 10%
$colour6 = "orange/brightness(+0.1)";  // l + 0.1 (the same as +10%)
$colour7 = "orange/brightness(-0.1)";  // l - 0.1 (the same as -10%)

The default value for saturation completely desaturates the colour, but the default brightness value is 1.2, which increases the brightness by 20% of its current value. Leading + and - symbols can be used to increase or decrease the brightness by a value instead of multiplying the current value.

Note: a brightness of 0 is black and a brightness of 1 (or 100%) is white.

Brightness filters

View source

Hue

The hue function is a bit simpler than saturation and brightness, and only takes a positive or negative value that shifts the hue around the colour wheel by an angle in degrees:

$colour1 = "red/hue";       // default value 60, red -> yellow
$colour2 = "red/hue(30)";   // orange
$colour3 = "red/hue(120)";  // green
$colour4 = "red/hue(180)";  // cyan
$colour5 = "red/hue(-60)";  // purple
$colour6 = "red/hue(-120)"; // blue

The default value for the hue function is 60, which is deliberately quite a large change in colour to demonstrate that the filter function is working (and I couldn't think of a default value that made any more sense).

Hue filters

View source

Gradients

SVGGraph supports specifying vertical or horizontal linear gradients as an array of colours, with the colours assigned from top to bottom or left to right.

At least two colours must be used in gradients. The first and last colours will be at the edges of the filled area, with any other colours evenly spaced across the gradient. A final 'h' or 'v' in the array of colours specifies whether the gradient should be vertical (the default) or horizontal.

The colours can be in any of the formats listed in the colours section above, including use of the opacity value and filters, and with an optional gradient stop percentage at the start:

“[stop:]colour[:opacity][/filter]”

The stop value must be in the range 0-100. The opacity value must be in the range 0.0-1.0.

If a gradient stop value is not provided, the stops are evenly distributed. Multiple stops may have the same value to cause an instant change of colour or opacity.

Here are some examples:

// a horizontal gradient, red at both 
// sides and white in the centre
array('red', 'white', 'red', 'h');

// a vertical gradient, red at the top, 
// white in the centre, blue at the bottom
array('red', 'white', 'blue');

// a horizontal rainbow gradient
array('red', 'orange', 'yellow', 'green', 'blue', 'indigo', 'violet', 'h');

// the rainbow again, but quite desaturated
array('red/saturation(20%)', 'orange/saturation(20%)',
  'yellow/saturation(20%)', 'green/saturation(20%)',
  'blue/saturation(20%)', 'indigo/saturation(20%)',
  'violet/saturation(20%)', 'h'
);

// a horizontal gradient, 10% opaque in the centre
array('red','red:0.1','red','h'),

// a vertical gradient, 33% blue, then 
// from 50% opaque red to 100% opaque red
array('blue', '33:blue', '33:red:0.5', 'red'),

Gradients are supported by the bar graphs and for the filled area under line graphs, as well as the legend, tooltip, label, grid and graph backgrounds. Where gradients are not supported, the first colour in the array will be used to fill the area instead. The colour gradients defined in the example code above are shown in the bar graph below.

Example gradients

View source

Patterns

SVGGraph supports a number of simple predefined patterns, or you can define your own patterns using SVG code. The format of a pattern is an array beginning with a colour, a field called “pattern” which determines the pattern to use and some optional fields to fine-tune the appearance of the pattern:

$pattern = array(
  'red',                       // foreground colour of pattern
  'pattern' => 'cross',        // predefined pattern to use
  'back_colour' => '#ff0:0.3', // background colour
  'size' => 20,                // size of pattern
  'angle' => 45                // rotation angle
);

The only required fields are the initial colour and “pattern”. As with the gradients, the initial colour field is used as a fallback wherever patterns are not supported. The other fields all have default values, and are explained here:

back_colour: The background colour for the pattern, default white. Use NULL for a completely clear background.
size: The size of the repeating pattern square. The default size is 10 pixels.
angle: The rotation angle of the pattern, in degrees. Default is no rotation.
width: The width of the repeating pattern box. The default is the value of size.
height: The height of the repeating pattern box. The default is the value of size.

Each of the predefined pattern types is shown below (all using the default background colour, size and rotation). The name of each pattern has been used to label the bar containing the pattern.

Circles and spots

View source

Squares and checks

View source

Lines and crosses

View source

I've used contrasting colours on these examples to make it easier to see the edges - looking at it for too long could give you a headache though. The example below demonstrates a more muted palette and use of the size and angle options.

Less nauseating example

View source

User-defined patterns

If the predefined patterns don't give you the effect that you want, you can define your own pattern as a block of SVG code. You must provide the SVG markup as the “pattern” along with separate “width” and “height” fields.

This example shows how to use a tiled rectangular image pattern:

$pattern = array(
  'red',
  'pattern' => '<image xlink:href="images/patt.png" width="20" height="15"/>',
  'width' => 20,
  'height' => 15,
);

The initial colour field is still required as a fallback for places where patterns are not supported, though it does not have to appear in your pattern. The SVG markup you supply is not validated except to check that it contains “<” and “>”.

The “angle” and “back_colour” fields are supported for use with user-defined patterns, but the “size” option is replaced by the “width” and “height” options.

User-defined pattern example

View source

The example above uses the RSS feed icon rotated 45° on a pink background with decreasing opacity to draw the orange shapes. The blue and red patterns are created using figures, described in the next section.

Figure patterns

From version 3.1 figures can also be used as patterns, with the name of the figure you want to use replacing the main colour in the array:

$pattern = array(
  'round', // name of the figure
  'pattern' => 'figure',
  'size' => 12, // 12 pixel box
);

The colours used in figures are set in the figure option, so the foreground colour is not needed in the pattern details.

The “size”, “width” and “height” pattern options should be used to set the size of the repeating box containing the figure.

Figure patterns are drawn from (0,0) to (width,height) with anything outside this box truncated. This is different to how figures are used in markers, where the (0,0) point is the centre of the marker.

The figure used for the red and blue pattern above is shown here:

$settings = array(
  'figure' => array(
    array(
      'round',
      array(
        'circle', 'cx' => 4, 'cy' => 4, 'r' => 3, 'stroke' => 'blue'
      ),
      array(
        'circle', 'cx' => 6, 'cy' => 6, 'r' => 3, 'stroke' => 'blue'
      ),
      array(
        'circle', 'cx' => 5, 'cy' => 5, 'r' => 5, 'stroke' => 'red'
      ),
    ),
  ),
);

« Back to top of page SVG in HTML »