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).

types012345611363246423
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”.

types012345611363246423
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(
    array('#ccc','#fff','#ccc','h'),
  ),
  '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.

Positions

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.

flattaperpointfilleddiamondarrowteeround01020304050604060505545506055
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.

Filters

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:

all
Display all labels in dataset.
none
Display none of the labels. You can still use structured data to show specific item labels.
start
end
Display labels for the first/last entries in the dataset.
min
max
Display labels for the minimum/maximum values in the dataset.
peaks
troughs
Display labels where the data trend has changed direction.
nonzero
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.

024681012141618202201234567891011665588
4. Peaks and minimum
data_label_filter = "min peaks"
02468101214161820220123456789104422554422552288
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.

024681012141618202201234567891011445522444444
6. Every 3rd item offset by 2
data_label_filter = "3+2"
02468101214161820220369121511665588557766774466776644
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.

024681012141618202201234567891042122456543223455423484
8. Fading labels
data_label_fade_in_speed = 40
data_label_fade_out_speed = 5
024681012141618202201234567891042122456543223455423484
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.

0246810121416182022036912154212245654322345542348456764674747473663733664
10. Pop-to-front labels
data_label_popfront = true
0246810121416182022036912154212245654322345542348456764674747473663733664
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.

012345601234567566765LabelText
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 lists all the options tagged with data-label from the options index.

Data label options - Hide table

OptionDefaultDescription
data_label_angle 0 Text angle for data labels.
data_label_back_colour NULL Colour of label text border.
data_label_back_colour_outside NULL Alternative label text border colour.
data_label_callback NULL Callback function for data label text.
data_label_click false Enables click-to-show/hide for data labels.
data_label_colour "rgb(0,0,0)" Text colour for data labels.
data_label_colour_outside NULL Alternative text colour for data labels.
data_label_datetime_format "Y-m-d H:i:s" Date format for date/time keys in labels.
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_fill "white" Data label background colour.
data_label_filter NULL Limits the data labels displayed.
data_label_font "Arial" Font used for data labels.
data_label_font_adjust 0.6 Font adjust value for label text.
data_label_font_size 10 Font size for data labels.
data_label_font_weight "normal" Font weight for data labels.
data_label_line_spacing null Sets line spacing for data labels.
data_label_max_count 100 Maximum number of data labels to display.
data_label_min_space 0 Minimum space required for label.
data_label_opacity 1 Sets the opacity of 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_padding 3 Space inside data label boxes.
data_label_padding_x NULL Horizontal space in data label box.
data_label_padding_y NULL Vertical space in data label box.
data_label_popfront false Enables pop-to-front for data labels.
data_label_position "top" Position of data label.
data_label_round 0 Radius of data label corners.
data_label_same_size false Determines if all data labels should be the same size.
data_label_shadow_opacity 0.3 Opacity of data label shadows.
data_label_space 3 The space between the label and the data item.
data_label_tail_end "flat" Style of data label tail ending.
data_label_tail_end_angle 45 Angle of data label tail ending.
data_label_tail_end_width 10 Width of data label tail ending.
data_label_tail_length 3 Length of data label tails.
data_label_tail_width 5 Thickness of data label tails.
data_label_type "plain" The style of label to use.
label NULL Adds custom labels to the graph.
label_percent_decimals 2 Decimal places in label percentages.
label_position 0.75 Distance of label from centre.
show_data_labels false Displays labels for data items.
show_label_amount false Shows item amount in data label.
show_label_key true Shows item key in data label.
show_label_percent false Shows item percentage in data label.
units_before_label NULL String to display before value in data labels.
units_label NULL String to display after value in data labels.
Data label options

« Back to top of page Legends »