Colours, gradients and patterns
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 = 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.
Colour set and range functions
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.
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
#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
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
colourRangeHexHSL is set to
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
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.
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.
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
"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.
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
where it is appropriate, or ignored in places where it would not be useful.
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.
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
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.
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).
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:
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.
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:
- The background colour for the pattern, default white. Use
NULLfor a completely clear background.
- The size of the repeating pattern square. The default size is 10 pixels.
- The rotation angle of the pattern, in degrees. Default is no rotation.
- The width of the repeating pattern box. The default is the value of
- The height of the repeating pattern box. The default is the value of
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.
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.
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.
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.
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
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' ), ), ), );