SVGGraph data labels

« Return to SVGGraph page

Skip to:

Version 2.18 of SVGGraph merged all the previous support for labels on bar graphs and pie graphs into one system that works for all the graph types. This page shows some of the options available and how to use them.

Types of label

Figure 1 below shows all the types of label available with the data_label_type option (using a grouped bar graph with a dataset for each label type).

1. Data label types

The styles used for these labels are: “plain”, “box”, “bubble” and “line”, along with these new styles added in version 2.26: “circle”, “square”, “linecircle”, “linebox”, “linesquare” and “line2”.

2. Restyled labels

Figure 2 above uses the same data and the same choice of label types, but modifies the styling options a bit. The settings that it uses for the labels are shown in the code block below.

$settings = array(
  // other settings left out...
  'show_data_labels' => true,
  'data_label_type' => array('plain', 'box', 'bubble', 'line',
    'circle', 'square', 'linecircle', 'linebox', 'linesquare', 'line2'),
  'data_label_space' => 5,
  'data_label_back_colour' => array('#ccc', null, null, '#ccc'),
  'data_label_padding' => 5,
  'data_label_round' => 4,
  'data_label_tail_length' => "auto",
  'data_label_tail_width' => 5,
  'data_label_font_size' => 12,
  'data_label_fill' => array(
  'data_label_outline_thickness' => 2,
  'data_label_position' => 'above',
  'data_label_tail_end' => 'filled',
  'data_label_tail_end_width' => 16,

These options should be self explanatory, though a couple of them might seem a bit odd. The tail length of the bubble label is the 5 pixels specified, but the length of the line label is much longer. This is because line labels have a minimum length the same as the font size - much smaller and the line can look like a hyphen or other character.

The other strange option is the data_label_fill, which has an array inside an array. This is because I wanted to use a gradient to fill the label, which means using an array of colours. Since the option uses an array to choose different fill colours for different datasets, I had to wrap the gradient array inside the outer array. I hope that makes sense.


The data_label_position option specifies where the label goes, relative to the bars or markers (labels are positioned differently for pie slices). SVGGraph can ignore your choice when it doesn't make sense, like attempting to put the label inside a marker where it will not fit.

The table below shows the different positions that you can specify with the data_label_position option. The shaded area represents a bar on a bar graph, and the table cells are where the labels would be.

outside top left outside top inside left outside top outside top inside right outside top right
inside top outside left top left top top right inside top outside right
outside left left centre right outside right
inside bottom outside left bottom left bottom bottom right inside bottom outside right
outside bottom left outside bottom inside left outside bottom outside bottom inside right outside bottom right

The table doesn't look much like a bar on a graph though, and aligning the text the same way would be tricky, so here is a mock-up of a bar surrounded by labels in all the fixed positions:

Baroutside top leftoutside top inside leftoutside topoutside top inside rightoutside top rightinside top outside lefttop lefttoptop rightinside top outside rightoutside leftleftcentrerightoutside rightinside bottom outside leftbottom leftbottombottom rightinside bottom outside rightoutside bottom leftoutside bottom inside leftoutside bottomoutside bottom inside rightoutside bottom right
Label positions

Apart from these options, SVGGraph also supports “inner” and “outer” as alternatives to “inside” and “outside”, and the values “above” and “below” as alternatives to “outside top” and “outside bottom“.

You can also add two integers to the end of the position string as an X,Y offset, e.g. "top right -20 20".

Tail endings

The newer label styles that use filled line tails all support different end caps for the tail line. Figure 3 below uses the “linecircle” style and structured data to set each tail ending individually.

3. Tail endings

The value for the data_label_tail_end_width has been increased to 40 pixels to make the endings easier to see. When the tail width is not enough to draw the ending completely it will fall back to using a simpler ending style.


The data_label_filter option allows you to fine-tune which labels will be shown for a dataset. The default is to show all the labels, though you can use a combination of these options:

Display all labels in dataset.
Display none of the labels. You can still use structured data to show specific item labels.
Display labels for the first/last entries in the dataset.
Display labels for the minimum/maximum values in the dataset.
Display labels where the data trend has changed direction.
Display labels for all values other than 0.

Figure 4 below uses “min” and “peaks” together to show labels for the minimum value at 2 and the three peaks at 7, 15 and 21.

4. Peaks and minimum
data_label_filter = "min peaks"
5. Every 3rd item
data_label_filter = "3"

As well as the keywords, you can also use a numeric step value with an optional offset, as demonstrated in figure 5 and figure 6. Without an offset, the first label (position 0) is shown, then label N, label 2×N, label 3×N, etc.

Figure 6 uses an offset of 2 (data_label_filter = "3+2") to label positions 2 (0 + 2), 5 (3 + 2), 8 (6 + 2), etc. If you want to use an offset, don't forget to enclose the filter value in quotation marks - otherwise the step and offset will be added together and give you a different step value.

6. Every 3rd item offset by 2
data_label_filter = "3+2"
7. Filter per-dataset
data_label_filter =
["peaks min", "start end 3+2"]

Figure 7 shows the use of an array to filter the two datasets differently. The first dataset is labelled on the peaks and minimum value, and the second dataset is labelled at both ends and every third entry starting with position 2.

Interactive label options

These options use Javascript to control label visibility when you move the cursor over (or click on) the bar, marker or pie slice. Figure 8 shows the fade in and fade out effects, with the labels fading in quickly and fading out slowly.

8. Fading labels
data_label_fade_in_speed = 40
data_label_fade_out_speed = 5
9. Click to show/hide labels
data_label_click = "hide"

Figure 9 uses the data_label_click option to toggle visibility of the labels when bars are clicked. The “hide” value means that the labels should be hidden initially, whereas a value of “show” will display all labels at the start.

Figure 10 demonstrates the effect of data_label_popfront. The labels are quite large in relation to the bars, so they overlap in places - with this option enabled, the label for the bar under the cursor will be popped to the front of all the other labels.

10. Pop-to-front labels
data_label_popfront = true
11. This one goes to eleven
data_label_fade_in_speed = 40
data_label_fade_out_speed = 5
data_label_click = ["hide","show"]
data_label_popfront = true

Figure 11 uses all the options together, this time using an array to make the click labels start hidden for the first dataset and shown for the second dataset.

The labels that are not already visible will fade in and out when you move the cursor over the bars. Clicking on a bar will keep it visible or allow it to fade out again, and the labels will pop to the front when the mouse is over the relevant bar.

Structured data labels

Most of the label options are also supported by the structured data structure array option, as demonstrated by the example graph below.

Structured data labels

Use the full data_label_* option name in your structure array to specify which options you want to change from the data. The structure array and data values used in the example graph are shown in the code below.

$settings = array(
  // other settings left out...
  'structure' => array(
    'key' => 0, 'value' => 1,
    'data_label_type' => 'dlt',
    'data_label_padding' => 'dlp',
    'data_label_round' => 'dlr',
    'data_label_position' => 'dlpos',
    'data_label_fill' => 'dlbg',
    'data_label_font' => 'dlf',
    'data_label_font_adjust' => 'dlfa',
    'label' => 'lbl',

$values = array(
  array(0, 5, 'dlt' => 'box',),
  array(1, 6),
  array(2, 6, 'dlpos' => 'left'),
  array(3, 7, 'dlt' => 'bubble'),
  array(4, 6, 'dlt' => 'bubble', 'dlp' => 10, 'dlr' => 8),
  array(5, 5),
  array(6, 3, 'dlpos' => 'above', 'dlt' => 'bubble', 'dlp' => 10, 'dlr' => 10,
    'dlf' => 'Times New Roman', 'dlfa' => 0.45,
    'lbl' => "Label\nText", 'dlbg' => array('#99f','#fff','#99f','h')),

This example also uses the older structured data option “label” to set the text for the last label explicitly.

Other details

These are just a few points that don't fit into the sections above.

— The data_label_max_count option limits the number of labels created for a dataset, to prevent generating huge numbers of labels that would probably overlap anyway. This option does not support arrays, as it is a simple sanity check and defaults to 100. The count applies after any filters, so if your labels appear to run out halfway across the graph, try a data_label_filter step of 2 (or increase data_label_max_count if you really want hundreds of labels).

— The units_label and units_before_label options were previously available for use with pie and bar labels, and will now work for all data labels. They do not alter the text of labels when it comes from a structured data label field.

— Several of the older pie graph label options are still required, as there are no equivalents for graphs in general. These options are show_label_key, show_label_amount, show_label_percent, label_position and label_percent_decimals. Pie graphs still use label_position for positioning the label because it uses a single value for the distance from the centre instead of the relative positions supported by data_label_position.

— The bar_total_* options supported by the stacked bar graphs use the same data labels code, so there are now several more options available for styling the total labels.

All the options

Just as a recap, here are all the data_label_* options. This table is also included as part of the “General options” section of the individual graph pages.

Data label options - Hide table

show_data_labels false Displays labels for bars, markers, pie slices
data_label_type "plain" The style of label to use. Options are "plain", "box", "bubble", "line", "circle", "square", "linecircle", "linebox", "linesquare" and "line2"
data_label_space 3 The space between the label and the data item.
data_label_font "Arial" Font used for label
data_label_font_size 10 Font size for data label
data_label_font_adjust 0.6 Font adjust value for label text
data_label_font_weight "normal" Font weight for data label
data_label_colour "rgb(0,0,0)" Text colour for data label
data_label_colour_outside NULL Text colour for data label when outside bar/slice. NULL for same colour as when inside
data_label_back_colour NULL Colour for label text border, or NULL for none
data_label_back_colour_outside NULL Colour for label text border when outside bar/slice, or NULL for same as when inside
data_label_position "top" Position of data label relative to bar/marker/slice. See the data labels page for details
data_label_angle 0 Text angle for data labels
data_label_padding 3 Space between data label text and edge of label box
data_label_padding_x NULL Horizontal space between data label text and edge of label box, overrides data_label_padding
data_label_padding_y NULL Vertical space between data label text and edge of label box, overrides data_label_padding
data_label_round 0 Radius of rounded corners for enclosed labels, or specifies a circular bounding box for plain text labels
data_label_fill "white" Background colour, gradient or pattern for box or bubble style data labels
data_label_outline_colour "rgb(0,0,0)" Edge colour for data labels
data_label_outline_thickness 1 Line thickness for data labels
data_label_tail_length 3 Length of label tail in pixels, or "auto" for automatic length calculation
data_label_tail_width 5 Thickness of tail
data_label_tail_end "flat" Type of line ending for labels with filled-line tails. Options are: "flat", "taper", "point", "filled", "diamond", "arrow", "tee" and "round"
data_label_tail_end_width 10 Width of tail ending in pixels
data_label_tail_end_angle 45 Angle of tail ending lines
data_label_shadow_opacity 0.3 Opacity of data label shadows
data_label_fade_in_speed 0 Fade in speed for data labels
data_label_fade_out_speed 0 Fade out speed for data labels
data_label_click false Set to TRUE to enable show/hide labels by clicking bar/marker/slice
data_label_popfront false Set to TRUE to pop the label of the bar/marker/slice under the cursor to top
data_label_filter NULL Filters the list of data labels to be displayed. See the data labels page for details
data_label_max_count 100 Maximum number of data labels to display for a dataset (after filtering)
data_label_min_space 0 Sets the minimum space required for a label to be shown. For vertical bars this is the height of the bar, for horizontal bars it is the width and for pie slices it is the angle in degrees. Has no effect on line and scatter graphs.
data_label_callback NULL Name of callback function for formatting data label text. The function will be called with three arguments: callback($dataset, $key, $value). The function should return a text string to display or NULL for no label. Takes precedence over structured data label values.
data_label_same_size false Set to TRUE to display all labels the same size, or an array of boolean values to set the option for each dataset separately
units_label NULL Units string to display after value in data labels
units_before_label NULL Units string to display before value in data labels
label NULL Custom labels to display on the graph. See the custom labels page for details.
Data label options

« Back to top of page Legends »