TagCanvas options

« Return to TagCanvas page

Skip to:

There are a number of options for modifying the way the cloud looks and behaves. This page explains how to set the options for your clouds to use and provides a list of all the available options.

Specifying options

There are two ways of specifying options for the stand-alone version of TagCanvas, and just the one way to set options for the jQuery plugin version.

Stand-alone - class variables

The first method for setting options is to set the corresponding class variables before calling the Start function:

 <script type="text/javascript">
 window.onload = function() {
  // set colour of text and outline of active tag
  TagCanvas.textColour = '#ffffff';
  TagCanvas.outlineColour = '#ff9999';
  TagCanvas.Start('myCanvas');
 };
 </script>

Using this method multiple tag clouds on the same page will share the same set of options.

Stand-alone - options array

The second way to configure the stand-alone version is to pass in the required options to the Start function as an array of name: value pairs in the third argument:

 <script type="text/javascript">
 var options = {
  textColour: '#fff',
  textHeight: 20,
  depth: 0.99
 };
 window.onload = function() {
  // use internal link list, so second argument is ''
  TagCanvas.Start('myCanvas', '', options);
 };
 </script>

I use the word "array" in its more generic sense here - the { x: y } syntax actually creates an unnamed Javascript object.

If you are using multiple clouds on a page, you could use both of the above methods at the same time - set the options that you want for all your clouds to share using class variables, then pass in the different options for each cloud as arrays.

jQuery - options array

For the jQuery plugin version of TagCanvas, the first method of setting options used by the standalone version is not available, so you must pass all the relevant options into the tagcanvas function using the array method:

 <script type="text/javascript">
 $(document).ready(function() {
   $('#myCanvas').tagcanvas({
     textColour : '#ffffff',
     outlineColour : '#ff9999'
   });
 });
 </script>

The options array is the first argument to the jQuery plugin function, as it gets the canvas details from the jQuery selector.

Options list

The following table lists all the options that are available in the latest version of TagCanvas.

When specifying an option the option name does not need to be in quotes. The value should be quoted with single or double quotes unless it is a number, an array or the Javascript keywords true, false or null.

The default values for each option are shown in the second column of the table below.

TagCanvas options - Hide table

OptionDefaultDescription
activeCursor "pointer" The CSS cursor type to use when the mouse is over a tag.
animTiming Smooth The animation timing function for use with the RotateTag and TagToFront functions. The values available are "Smooth" and "Linear".
bgColour null Background colour of tag, null for no background. The string "tag" means use the original link background colour.
bgOutline null Colour of tag background outline. Use null for the same as the text colour, use "tag" for the original link text colour.
bgOutlineThickness 0 Thickness of tag background outline in pixels, 0 for no outline.
bgRadius 0 Radius for rounded corners of background in pixels.
centreFunc null Function for drawing in centre of cloud. The function is passed in these parameters in order: canvas 2D context; canvas width; canvas height; centre X; centre Y. See the centre callback function page for details.
centreImage null Image to draw at centre of cloud. Uses a built-in centreFunc callback function to draw the image at full size in the middle of the canvas.
clickToFront null If set to a number, the selected tag will move to the front in this many milliseconds before activating.
decel 0.95 Deceleration rate when mouse leaves canvas.
depth 0.5 Controls the perspective (0.0-1.0)
dragControl false When enabled, cloud moves when dragged instead of based on mouse position.
dragThreshold 4 The number of pixels that the cursor must move to count as a drag instead of a click.
fadeIn 0 Time to fade in tags at start, in milliseconds.
freezeActive false Set to true to pause movement when a tag is highlighted.
freezeDecel false Set to true to decelerate when highlighted tags freeze instead of stopping suddenly.
frontSelect false Set to true to prevent selection of tags at back of cloud.
hideTags true Set to true to automatically hide the tag list element if TagCanvas is started successfully.
imageAlign "centre" Horizontal image alignment, one of “centre”, “left” or “right”.
imageMode null What to display when tag contains images and text.
null
Image if present, otherwise text.
image
Image tags only.
text
Text tags only.
both
Image and text on tag using imagePosition.
imagePadding 2 Distance between image and text when using an imageMode of “both”.
imagePosition "left" Position of image relative to text when using an imageMode of “both”. Options are “left”, “right”, “top“ or “bottom”.
imageRadius 0 Radius for image corners, in pixels. Also supports using a percentage which must be enclosed in a string, e.g. "20%".
imageScale 1 Amount to scale images by - the default of 1 uses the size they appear on the page. For no scaling (use the actual image size) set this to null.
imageVAlign "middle" Vertical image alignment, one of “middle”, “top” or “bottom”.
initial null Starting rotation speed, with horizontal and vertical values as an array, e.g. [0.8,-0.3]. Values are multiplied by maxSpeed.
interval[1] 20 Interval between animation frames, in milliseconds.
lock null Limits rotation of the cloud using the mouse. A value of "x" limits rotation to the x-axis, "y" limits rotation to the y-axis. A value of "xy" will prevent the cloud rotating in response to the mouse - the cloud will only move if the initial option is used to give it a starting speed.
maxBrightness 1.0 Brightness (opacity) of tags at front of cloud (0.0-1.0).
maxSpeed 0.05 Maximum speed of rotation.
minBrightness 0.1 Brightness (opacity) of tags at back of cloud (0.0-1.0).
minSpeed 0.0 Minimum speed of rotation when mouse leaves canvas.
minTags 0 The minimum number of tags to show in the cloud. If the number of links available is lower than this value, the list will be repeated. The maximum supported value is 200. The repeatTags option takes precedence over minTags.
noMouse false Set to true to prevent any mouse interaction. The initial option must be used to animate the cloud, otherwise it will be motionless.
noSelect false Set to true to prevent the selection of tags.
noTagsMessage true Displays “No tags” instead of an empty canvas when there are no tags available.
offsetX 0 Offsets the centre of the cloud horizontally (measured in pixels)
offsetY 0 Offsets the centre of the cloud vertically (measured in pixels)
outlineColour "#ffff99" Colour of the active tag highlight. This can be a colour to use for all tags, or one of these options to set the colour differently for each tag:
tag
Use the text colour from the original tag link
tagbg
Use the background colour from the original tag link
See also the “outline” weightMode for another way to set the highlight colour.
outlineDash 0 Size of marching ants dash for outline/classic highlights, 0 for no dashes
outlineDashSpace 0 Size of space between marching ants dashes, 0 for same as outlineDash
outlineDashSpeed 1 Speed of marching ants animation, 0 for no movement, negative for reverse
outlineIncrease 4 Number of pixels to increase size of tag by for the “size” outline method. Negative values are supported for decreasing the size.
outlineMethod "outline" Type of highlight to use. Options are:
outline
An outline at the same depth as the active tag.
classic
Old-style outline on top of all tags.
block
Solid block of colour around the active tag.
colour
Changes the colour of the text or image of the current tag to the outlineColour value.
size
Increases the size of the tag, using the outlineIncrease option for the amount.
none
No highlighting at all.
outlineOffset 5 Distance of outline from text, in pixels. This also increases the size of the active area around the tag.
outlineRadius 0 Radius for rounded corners on outline box in pixels
outlineThickness 2 Thickness of outline in pixels
padding 0 Amount of space around text and inside background.
pinchZoom false Set to true to enable zooming in and out of the cloud by pinching on touchscreen devices.
pulsateTime 3 Pulse rate, in seconds per beat
pulsateTo 1.0 Pulsate outline to this opacity (0.0-1.0)
radiusX 1 Initial size of cloud from centre to sides.
radiusY 1 Initial size of cloud from centre to top and bottom.
radiusZ 1 Initial size of cloud from centre to front and back.
repeatTags 0 The number of times to repeat the list of tags in the cloud. The maximum supported value is 64. This option overrides the minTags option.
reverse false Set to true to reverse direction of movement relative to mouse position.
scrollPause 0 Animation delay in milliseconds for when the page is being scrolled. Applies to all TagCanvas instances on the page.
shadow "#000000" Colour of the shadow behind each tag.
shadowBlur 0 Amount of tag shadow blurring, in pixels.
shadowOffset [0,0] X and Y offset of the tag shadow, in pixels.
shape "sphere" The shape of the cloud. Currently supported are sphere, hcylinder for a cylinder that starts off horizontal, vcylinder for a cylinder that starts off vertical, hring for a horizontal circle and vring for a vertical circle. You may also provide the name of a function to use for generating the shape. See the TagCanvas shapes page for details and examples.
shuffleTags false Set to true to randomize the order of the tags.
splitWidth 0 If greater than 0, breaks the tag into multiple lines at word boundaries when the line would be longer than this value. Lines are automatically broken at <br> tags.
stretchX 1 Stretch or compress the cloud horizontally.
stretchY 1 Stretch or compress the cloud vertically.
textAlign "centre" Horizontal text alignment, one of “centre”, “left” or “right”.
textColour[2] "#ff99ff" Colour of the tag text - empty string or null to use the colour of the original link.
textFont[2] "Helvetica, Arial,
sans-serif"
Font family for the tag text - empty string or null to use the font of the original link.
textHeight 15 Height of the tag text font (in pixels).
textVAlign "middle" Vertical text alignment, one of “middle”, “top” or “bottom”.
tooltip[3] null Sets tooltip display method: null for no tooltips; native for operating system tooltips; div for div-based.
tooltipClass[3] "tctooltip" Class of tooltip div.
tooltipDelay[3] 300 Time to pause while mouse is not moving before displaying tooltip div, in milliseconds.
txtOpt true Text optimisation, converts text tags to images for better performance.
txtScale 2 Scaling factor of text when converting to image in txtOpt mode.
weight[4] false Set to true to turn on weighting of tags.
weightFrom[4] null The link attribute to take the tag weight from. The default of null means that the weight is taken from the calculated link font size.
weightGradient[4] {0:'#f00', 0.33:'#ff0',
0.66:'#0f0', 1:'#00f'}
The colour gradient used for colouring tags, backgrounds, etc. when using a colour-based weight mode.
weightMode[4] "size" Method to use for displaying tag weights. Should be one of:
size
Display more significant tags in a larger font size.
colour
Display tags using colour values from the weightGradient option.
both
Use both size and colour to visualise weights.
bgcolour
Use a weightGradient to set the tag background colour.
bgoutline
Use a weightGradient to set the tag background outline colour. Tag background outlines must be enabled using the bgOutlineThickness option.
outline
Use a weightGradient to set the tag highlight colour.
weightSize[4] 1.0 Multiplier for adjusting the size of tags when using a weight mode of size or both.
weightSizeMax[4] null Maximum font size when weighted sizing is enabled.
weightSizeMin[4] null Minimum font size when weighted sizing is enabled.
wheelZoom true Enables zooming the cloud in and out using the mouse wheel or scroll gesture.
zoom 1.0 Adjusts the relative size of the tag cloud in the canvas. Larger values will zoom into the cloud, smaller values will zoom out.
zoomMax 3.0 Maximum zoom value.
zoomMin 0.3 Minimum zoom value.
zoomStep 0.05 The amount that the zoom is changed by with each movement of the mouse wheel.
TagCanvas options

« Back to top of page Weighted tags »