Browser requirements
iTOL uses Javascript and HTML5 Canvas element to draw the trees. Any modern, standards-supporting browser should work fine. Display of very large trees (more than 10'000 leaves) or trees with very many datasets will be greatly influenced by the speed of your computer and available memory. In our tests, Webkit based browsers offer the best performance (Chromium/Google Chrome, Opera and Safari).
iTOL's user account login and several other features require browser cookies, so make sure your browser or firewall are not filtering them.
If you encounter problems with tree or dataset display, please contact the developer.
User interface
Check our user interface video tutorial.
- Main tree display shows the current tree. To move/pan the tree, simply click and drag with your mouse. You can also use the mouse wheel to pan the tree. Keep the Shift key pressed while scrolling the wheel to pan horizontally, and the Ctrl key to pan vertically. If you simultaneously keep the Alt/Meta pressed, panning speed will increase.
- Zoom controls: In addition to mouse wheel, zoom icons can be used to change the display zoom level. Clicking the 'zoom fit' icon will return the tree to the initial zoom/position.
- Other functions: Hover over the info icon to display basic information about the current tree. Search icon can be used to quickly find a specific leaf or internal node.
- Main control panel: Most iTOL's functions are available here, split over 4 tabs.
- Colored ranges/datasets box: If colored ranges or datasets are present in the tree, they will be listed here.
The main control box and all other dialogs/legends can be freely moved by clicking on their title bars and dragging them.
Functions
Check our iTOL functions video tutorial.
Display modes
iTOL can display phylogenetic trees various modes:
- normal (rectangular)
- slanted (triangular)
- circular
- curved branches (in normal or circular modes)
- unrooted (radial), equal-angle
- unrooted (radial), equal-daylight
To switch the display mode, click the corresponding button in the Display mode section of the Basic controls tab.
Trees which contain branch length information will be displayed as phylograms by default. To display them as cladograms and ignore the branch length information, select the Ignore option in the Branch lengths section of the Basic controls tab.
Slanted mode is a special version of the normal display mode. To display a tree in slanted mode, switch the display mode to Normal first, and then set the Slanted option on the Basic controls tab to Yes.
Tree display can be further customized through several options in the Basic and Advanced control option tabs:
- Rotation: is used to rotate whole tree clockwise by the specified angle (in degrees)
- Arc: is used to define the total angle which the tree will cover in circular mode (default is 350°)
- Inverted display: normal and circular displays can be inverted by using this option
- Label font/style: change the font family, style, size and color of all tree labels
- Branch lines: change the width and color of tree branches, and switch between straight and curved lines
- Scaling factors: increase/decrease the horizontal or vertical scale, stretching/shrinking the tree in the selected dimension
- Leaf sorting: by default, iTOL will put the branches with fewer leaves to the "top" (when looking at a tree in normal mode), resulting in a nicer, stair-like display. This option can be used to disable the sorting and use the original order as defined in the tree file.
- Equal-daylight: unrooted display mode uses the so called 'equal-angle' algorithm by default, which normally produces crowded leaves with large empty areas between clades. 'Equal-daylight' algorithm (e.g. citation) produces layouts which show the tree structure more clearly. Up to 5 iterations of the algorithm can be applied. Note that branch overlaps can occur when more than 1 iteration is applied. Using mid-point rooted trees usually minimizes the overlap issues.
Support and other metadata values
If a tree contains bootstrap information, or other metadata (such as various MrBayes metadata fields), these can be visualized by selecting Display under Bootstraps / metadata section of the Advanced controls tab. Select the desired metadata source using the Data source selector, and set the Display range values to select the range which should be displayed. By default, all values are included.
Note that non-numeric metadata sources can only be visualized as branch colors or text labels.
The metadata can be visualized in 4 different ways:
- Symbol: select the shape type, minimum and maximum size and the color. Minimum/maximum sizes selected will be used as the radii/sizes for the shapes corresponding to the minimum/maximum metadata value. Note that minimum size can be larger than maximum. Position of the symbol along the branch can be adjusted.
- Text: values will be displayed as text labels on the branches. Font size, numeric style and position of the label can be adjusted.
- Color: tree branches will be colored according to their metadata values and the color gradient defined in the control box. For non-numeric metadata sources, colors will be assigned automatically, and can be edited by clicking the Define colors button.
- Width: tree branch widths will be set according to their metadata values. Minimum/maximum widths selected will be used as the widths for the branches with minimum/maximum metadata value. Note that minimum width can be larger than maximum.
If the metadata is visualized as symbols or branch colors, a corresponding legend can be added to the tree by setting the Legend toggle to On.
Branch lengths and internal tree scale
If a tree contains branch length information, these can be visualized by selecting Display under Branch lengths section of the Advanced controls tab. Values will be displayed as text labels directly on the branches. Position, size and numeric style of the labels can be adjusted.
By selecting the Display as age option, node ages will be displayed instead of raw branch length values. Farthest leaf in the tree has the age zero, and the age increases towards the root of the tree.
In addition, an internal tree scale and axis can be displayed by selecting Display under Internal tree scale section of the Advanced controls tab. You can set the interval values, colors and widths for 2 different sets of the scale lines. In addition, a set of fixed lines can be defined in the 'Fixed' input box. Provide a comma delimited list of values, and scale lines will be displayed at each value starting from the tree root (or tree top, if the scale is inverted). Each set of lines can be displayed as dashed by selecting the corresponding checkbox.
Time scale mode
In time scale mode, you can customize the tree scale to display other values, and not branch lengths directly. Simply provide the numeric value which should be used for the tree root (or tree top, if the scale is inverted), and the scaling factor for the branch lengths.
Pruning the tree
Template file: prune.txt
Pruning is a process of selecting one or mode branches from the original tree and creating a new, smaller tree.
To start pruning, click on any node and select Add node to pruned tree. A small dialog will be displayed showing the total number of leaves selected. Nodes which are part of the selected clades can also be removed by clicking them and selecting the corresponding function.
When you have selected all nodes of interest, click the Prune tree button to display the new tree.
You can also use the template file prune.txt to specify a list of nodes to prune. Simply drop the file onto the tree, and all listed nodes will be included in the pruned tree.
Collapsing clades
Template file: collapse.txt
To collapse a clade, click on any internal tree node and select Collapse node.
You can also use the template file collapse.txt to specify a list of nodes to collapse. Simply drop the file onto the tree, and all listed clades will be collapsed.
By default, collapsed clades will be displayed as triangles with two side lengths proportional to the distances to node's closest and furthest leaves. The shape used to display collapsed clades can be changed under Collapsed nodes section of the Advanced controls tab.
Working with tree views
Click the Save/restore view button in the corner of the main controls box to access the functions related to tree views.
All parameters currently selected can be saved as defaults for that tree by clicking Save as default view for this tree. Alternatively, you can save them as a named view, which will be available through the Restore view menu.
Clicking the Save as default view for the whole project will apply the current tree view to this and all other trees present in the same user project. Settings will also be stored, and will automatically apply to any future trees uploaded to the same project. With project defaults, the following settings are NOT saved: rerooting, node rotation, collapsed nodes, node editing and pruning information.

Working with tree views
Uploading trees
To upload a tree, go to the 'Upload' page. If you are logged into your iTOL account, you can use the upload button at the bottom of each project box. You can also simply drag and drop one or multiple tree files onto the footer of each project box.
Your trees should be in plain text files, and in one of the supported formats (Newick, Nexus, PhyloXML or Jplace). When uploading .jplace files, make sure that the file extension is .jplace, or the format will not be recognised correctly.
Support for NHX and MrBayes metadata
iTOL can parse various metadata from MrBayes and NHX trees. All metadata values will be extracted, and available for visualization through the 'Bootstrap/metadata' section in the advanced controls tab. In addition, NHX tag name can be used to specify internal node IDs (see examples below).
Support for QIIME 2 QZA trees
iTOL supports direct upload of QZA trees generated by QIIME 2. After the initial upload, these trees can be further annotated using other QZA files. Simply drop the QZA file onto the tree, or upload it through the "+" button in the bottom right of the tree display.
The following QZA types are supported:
- FeatureData[Taxonomy] (e.g. taxonomy.qza): Leaf labels will be automatically assigned, and confidence values will appear as a bar chart dataset.
- FeatureTable[Frequency] (e.g. table.qza, table-deblur.qza): A multi value bar chart will be created with sample frequencies in different tree leaves.
- FeatureData[AlignedSequence] (e.g. aligned-rep-seqs.qza, masked-aligned-rep-seqs.qza): Multiple sequence alignment dataset will be created automatically.
Example trees in Newick format:
Tree with bootstraps and branch lengths: (A:0.1,(B:0.1,C:0.1)90:0.1)98:0.3); A, B, C : leaf names 0.1, 0.3 : branch lengths 90,98 : bootstrap values Tree with internal node IDs: (A:0.1,(B:0.1,C:0.1)INT1:0.1[90])INT2:0.3[98]); A, B, C : leaf names INT1, INT2 : internal node IDs 0.1, 0.3 : branch lengths 90,98 : bootstrap values Tree with NHX style metadata: (A:0.1,(B:0.2,(C:0.2,D:0.3):0.4[&&NHX:conf=0.01:name=NODE1]):0.5); A, B, C : leaf names internal node will have the ID NODE1 metadata value 'conf' will be available for visualization MrBayes tree with full metadata: ( n1[&prob=1.00000000e+00,prob_stddev=0.00000000e+00,prob_range={1.00000000e+00,1.00000000e+00}, prob(percent)="100",prob+-sd="100+-0"]:7.827820e-02[&length_mean=7.95052056e-02, length_median=7.82782000e-02,length_95%HPD={5.41722800e-02,1.09222000e-01}], n2[&prob=1.00000000e+00,prob_stddev=0.00000000e+00,prob_range={1.00000000e+00,1.00000000e+00}, prob(percent)="100",prob+-sd="100+-0"]:1.029146e-01[&length_mean=1.03620749e-01, length_median=1.02914600e-01,length_95%HPD={7.64916100e-02,1.34490900e-01}] )[&prob=1.00000000e+00, prob_stddev=0.00000000e+00,prob_range={1.00000000e+00,1.00000000e+00}, prob(percent)="100",prob+-sd="100+-0"]:1.905703e-01[&length_mean=1.91679099e-01, length_median=1.90570300e-01,length_95%HPD={1.37001000e-01,2.53530500e-01}]; n1, n2: leaf names prob, prob_stddev, prob(percent) ... : various metadata fields which can be used in 'Bootstraps/metadata' section
Annotating trees
iTOL annotation editor for spreadsheets
The simplest way of creating and editing datasets and other tree annotations in iTOL is the iTOL annotation editor for Google Sheets or Microsoft Excel. It offers full access to your iTOL account though the familiar spreadsheet user interface. The following functions are supported:
- Editing of tree node labels
- Creation and editing of colored ranges
- Creation and editing of datasets, with support for most popular types
- Error reporting directly in the spreadsheet user interface, with dynamic highlighting of cells with invalid data
More information with detailed help and a tutorial video is available on the iTOL annotation editor web site.
Annotating on the web
Check our tree annotation video tutorial, then play with an example tree and annotations.
In iTOL, all tree annotation is done by simply drag-dropping a plain text data file onto the tree display, or interactively by using various functions in the web interface. When iTOL detects that you are dragging a file over the tree, the display will change and show the message shown on the right. You can drop multiple files at once, and they will be processed sequentially.
In addition to drag and dropping, you can use the + button in the bottom right corner of the tree display to upload annotation files using a standard file selection box.
Template files for all available annotation types are available in the corresponding sections below. You can also download a ZIP file with all available templates. All template files include comments and detailed instructions. If you have trouble understanding any of the template options, or encounter issues in annotating your trees, please contact the developer.
All annotation files start with an ID keyword (which identifies the annotation type), followed by the SEPARATOR keyword. The selected separator has to be used throughout the file. Most annotation files contain a few mandatory options (for example, LABEL and COLOR) and a set of optional settings. All optional settings can be later adjusted in the web interface through the 'Datasets' tab of the functions box. The actual data associated to each node follows after the DATA keyword.
We have prepared a ZIP archive (example_data.zip) which contains our Tree of Life (filename tree_of_life.tree.txt) and various example annotation files, filled mostly with random data. Try uploading the tree, and then dropping some of the annotation files onto it to get an idea how to prepare the annotations for your own trees.
iTOL also supports QIIME 2 QZA feature/annotation files, which can be dropped onto the trees uploaded through a QIIME 2 QZA. See the QIIME section above for details.
Saving annotation changes
Whenever any tree annotation is added or changed, a warning dialog shown on the right will be displayed. If you want to commit your newly added or updated annotations, simply click Save all changes button. This will store all new data into the iTOL database. If you do not save them, all changes will be lost when the tree is reloaded, or the browser page closed.
Internal node identifiers
When assigning annotations to internal tree nodes, there are two possibilities:
- Internal nodes already have IDs assigned (as shown in the tree above): In this case, you can use these IDs directly in all annotation template files.
- There are no internal tree node IDs: You can specify the nodes using the Last common ancestor method. Select two leaves whose last common ancestor is the
node of interest, and use their IDs separated with three minus signs ('---') or a vertical line ('|'). In the example on the right:
Gallus_gallus|Homo_sapiens = node INT1 Mus_musculus---Homo_sapiens = node INT2 Pan_troglodytes|Homo_sapiens = node INT3
Depending on the dataset type, values associated to internal nodes will only be visible when the node is collapsed. However, such dataset types have an additional option Show internal values, which can force the display of internal node values even when these are not collapsed. Note that this could result in overlapping displays, if there are values for the leaf nodes present as well.
Branch and label colors and styles
Template file: colors_styles_template.txt
Supported in the iTOL annotation editor for spreadsheets
Colors and styles for the branches and labels can be set using the TREE_COLORS annotation file, or interactively through the node popup menus. Simply click on any node or label, and select the desired function from the 'Editing' section of the popup menu.
By using the TREE_COLORS annotation file, you can define the colors, styles and widths/sizes for each individual node or label in the tree. To assign styles to internal tree nodes, check relevant section above.
In addition to setting the label text color, a separate background color can be specified for each label.
Note that most of the TREE_COLORS functionality is also available through the Branch/label styles dataset, which allows multiple color styles to be defined (by using several separate styles datasets). TREE_COLORS annotation should be used for static, permanent style annotations.
Branches with gradient lines
When the Branch gradients control is set to On, branch lines will be colored with a gradient starting with the ancestor node color towards the actual node color.
This feature can be used regardless of the source of branch colors (metadata based coloring, TREE_COLORS annotation, Branch styles dataset or direct manual color settings).
Colored ranges
Template file: colors_styles_template.txt
Supported in the iTOL annotation editor for spreadsheets
Colored ranges provide simple highlighting of certain nodes, clades or sets of leaf labels. Use the buttons in the colored ranges legend box to switch between the range coverage modes (either Labels only or Full clades).
Colored ranges can be defined in the TREE_COLORS annotation file, or interactively through the node popup menus. Simply click on any node or label, and select the desired function from the 'Color' submenu. You can simply create new colored ranges or add nodes to existing ranges.
By using the TREE_COLORS annotation file, you can define a large number of colored ranges without the need to use the interactive mode. Check the template file for details and instructions. To assign ranges to internal tree nodes, check relevant section above.
If you need a colored ranges legend in the exported tree figures, you can create it using a toggle button on the 'Export' control tab. Note that the colored ranges legend is sortable. Simply click a range label in the Colored ranges box, and drag it to a new position.
Changing leaf labels text and internal node names
Template file: labels_template.txt
Supported in the iTOL annotation editor for spreadsheets
To quickly change the text assigned to leaf nodes, or to assign/change names for internal tree nodes, use the LABELS annotation file. Leaf labels text can also be changed interactively, by clicking on a label and selecting the Edit option from the Label submenu.
Note that this annotation file only changes the actual text of the labels. If you want to assign colors, font sizes or styles, please check the colors/styles section.
Defining node popup information
Template file: popup_info_template.txt
If you want to display additional information in the popup windows which appear when hovering mouse pointer over tree nodes or labels, you can use the POPUP_INFO annotation file.
For each node ID, you can define both the popup title and the content. Content can be in plain text or any valid HTML (including links to external web sites, or IMG tags pointing to external images).
If you encounter problems with popup display or corruption of the tree display when using complex HTML, please contact the developer.
Manual annotations / drawing tools
iTOL provides a set of very simple drawing tools which allow adding basic manual annotations to trees. These are not intended to be used for any complex drawing / annotation, you should use a proper vector graphics editor if required.
Click the Manual annotations button on the left side of the screen to open the tool panel, then click any of the tool buttons to select it. The following tools are available:
Ellipse/circle: click anywhere in the tree to set the center, and drag to draw an ellipse. Keep the Shift key pressed to draw a circle.
Rectangle/square: click anywhere in the tree to set the top left corner, and drag to draw a rectangle. Keep the Shift key pressed to draw a square.
Line/shape: click anywhere in the tree to set the starting point. Click elsewhere to draw a line, or click and drag to draw a Bezier curve. Keep clicking to continue adding lines / curves. Press the Enter/return key to complete the line/polygon, or click the starting point to complete the shape.
Freehand drawing: click anywhere in the tree to set the starting point, and drag to draw.
Text label: click anywhere in the tree set the label position, and enter the text when prompted.
Move/rotate/scale: click any existing manual drawing or text label, and drag it to a new position. While dragging the mouse, keep the Shift key pressed to rotate. Keep the Ctrl key pressed to scale the object horizontally, or keep the Alt / Meta key pressed to scale it vertically. Hold both Ctrl and Alt keys to scale uniformly.
Edit objects: When this tool is selected, all manually drawn paths and objects will be highlighted. Click and drag any path point to move it. Click and drag the point handles to adjust the curves.
Delete objects: click any object or text label to delete it.
- Clear all: remove all manual annotations. Note that this cannot be undone.
Note that all manual annotation positions and sizes are specific for the currently selected tree display. If you change the display mode, or change the tree structure, the annotation positions will NOT change accordingly.
You can save your manual annotations, and they will be restored when you open the tree again. See Saving annotation changes section above.
Datasets
iTOL can annotate trees with several types of data, described in detail below. Simply customize a dataset template file with your information and drop it onto the tree. Several dataset types can be created directly in the iTOL web interface.
Dataset display can be switched off and on by using the toggle button () next to each dataset label in the legend box.
Access the dataset options by clicking the corresponding gear icon () in the legend box.
To delete a dataset, hover over its label in the legend box and a click the trashcan icon that appears ().
Number of datasets is limited only by the available memory, and they can all be displayed simultaneously. You can adjust the dataset position by changing the Left margin option, which can be positive or negative.
Several dataset types support editing of their underlying data directly in the web interface. If supported, a button labeled Edit raw data will be present below the dataset options.
Creating datasets interactively
Check our dataset creation tutorial.
Supported in the iTOL annotation editor for spreadsheets
Some dataset types can be created directly in the web interface, without any text templates. Simply click the 'Create a dataset' button in the 'Datasets' control tab (or in the Datasets floating legend box), specify the label and type, and enter the data through the simple spreadsheet-like interface.
For dataset types which support multiple value fields for each node (e.g. Multi value bar charts, Pie charts or Binary datasets), a separate section of the dataset editor is provided to add, remove or change the individual fields.
To edit the data in any cell, double click it and type or select the value, depending on the cell type. Tree node column will provide auto-complete based on the tree IDs and labels. You can select internal nodes which do not have IDs assigned by using the last common ancestor method.
In addition to manual editing of cells, you can simply paste the information from external spreadsheets (for example from Microsoft Excel). Make sure the selected data columns match the dataset editor. Tree node IDs should always be in the first column.
Existing datasets, even if created from template files, can be edited at any time. Simply click the Edit raw data button in the dataset options tab to access the dataset editor interface.
When you are finished with entering new data, or editing existing one, don't forget to save the changes.
Dataset legends
In addition to the regular Datasets legend box, which contains the dataset labels and toggle/configuration buttons, you can define individual dataset legends. These will be displayed only when the dataset is visible, and will also be included in the exported tree figures.
Individual legends are defined in the dataset annotation files using the fields LEGEND_TITLE, LEGEND_SHAPES, LEGEND_COLORS and LEGEND_LABELS.
Optionally, you can vary the sizes of individual shapes by using LEGEND_SHAPE_SCALES line. For each shape, set a scale from 0 to 1.
Legends can also be created or edited by clicking the Edit legend button in the dataset options tab.
By default, legends will be automatically positioned one below the other on the left side of the tree. You can click and drag any legend to change its position, and save it by clicking the button in the dataset settings tab. You can also use LEGEND_POSITION_X and LEGEND_POSITION_Y values in the template to set the legend position.
Shapes are defined with a number between 1 and 6, or with any domain shape code:
1 | square | ![]() |
2 | circle | ![]() |
3 | star | ![]() |
4 | right triangle | ![]() |
5 | left triangle | ![]() |
6 | checkmark | ![]() |
Dataset scales
Several dataset types support the display of custom scales: Simple bar chart, Multi value bar chart, Boxplot and Protein domains. Scales are defined in the dataset annotation files using the field DATASET_SCALE.
Scales can also be created or edited by clicking the Edit scale button in the dataset options tab.
You can simply provide a list of values which define where the scale lines will be displayed (Example 1 below and in the figure on the right). Optionally, it is possible to define the line color and a label to be displayed with each line, as well as the line style (Example 2 below and in the figure on the right). Label, color, width and style (normal or dashed) for a scale line are added after the value, separated with dashes (format: VALUE-LABEL-COLOR-WIDTH-DASHED-LABEL_SCALE_FACTOR):
- VALUE: the value where the scale line will be displayed
- LABEL: label to be displayed next to the scale line
- COLOR: color of the scale line
- WIDTH: width of the scale line in pixels. If omitted, line will be 1 px wide.
- DASED: if set to 1, scale line will be dashed. If omitted or set to 0, scale line will be normal.
- LABEL_SCALE_FACTOR: font size of the scale label will be multiplied by this number, if specified
To specify negative values, use the keyword − instead of the actual minus sign (e.g. to draw a line at -200px, the value definition would be −200)
Example 1: DATASET_SCALE,100,200,300,400,500 Example 2: DATASET_SCALE,100-line1-#ff0000-1-1-2,200-line2-#00ff00-5-0-1,300-line3-#ff0000-1-1-5,400-line4-#00ff00-10-0-1,500-line5-#ff0000-5-1-1
Dataset types
Different dataset types are described below, with links to their corresponding template files. Templates are commented and contain one or more examples explaining various options. If you encounter any problems with using these templates, or do not understand some of the available options, please contact the developer.
Binary
Template file: dataset_binary_template.txt
Supported in the iTOL annotation editor for spreadsheets
Binary datasets are visualized as filled or empty symbols, depending on the value associated with a node (0 or 1). Each node can have multiple associated values, and each value will be represented by a symbol (defined in FIELD_SHAPES) with corresponding color and label (defined in FIELD_COLORS and FIELD_LABELS). Possible values for each node are:
- 1 : filled shape
- 0 : empty shape
- -1 : shape completely omitted
Shapes are defined in FIELD_SHAPES, with a number between 1 and 6:
1 | square | ![]() |
2 | circle | ![]() |
3 | star | ![]() |
4 | right triangle | ![]() |
5 | left triangle | ![]() |
6 | checkmark | ![]() |
Simple bar charts
Template file: dataset_simplebar_template.txt
Supported in the iTOL annotation editor for spreadsheets
In simple bar charts, each node is associated to a single numeric value which is displayed as a bar outside the tree. Maximum value in the dataset will correspond to MAXIMUM_WIDTH specified, while COLOR field will define the color of the bars. These can be changed later through the dataset options tab.
In the example on the right, three simple bar charts are displayed. Their position and relation of the individual bars has been adjusted through MARGIN, BAR_SHIFT and HEIGHT_FACTOR options, directly though the web interface.
Multi value bar charts
Template file: dataset_multibar_template.txt
Supported in the iTOL annotation editor for spreadsheets
In multi-value bar charts, each node is associated to multiple numeric values, which are displayed as a stacked or aligned bar chart outside the tree.
Individual fields (values) must have a corresponding label and color, which are defined using FIELD_LABELS and FIELD_COLORS. Maximum sum of field values in the dataset will correspond to MAXIMUM_WIDTH specified, which can also be changed later through the dataset options tab.
Note about the scales: If a custom scale is defined in a multi value bar chart dataset, and individual fields are aligned, the scale will be duplicated and shown in each individual field (like in the example on the right).
Pie charts
Template file: dataset_piechart_template.txt
Supported in the iTOL annotation editor for spreadsheets
In pie chart datasets, each node is associated to multiple numeric values, which are displayed as a pie chart directly on the node branch, or outside the tree. Individual fields (values) must have a corresponding label and color, which are defined using FIELD_LABELS and FIELD_COLORS.
First value after each node ID in the DATA section specifies the pie chart position. If this value is -1, pie chart will be external (ie. displayed outside the tree). Otherwise, it should be a number between 0 and 1, and the pie chart will be positioned at the specified value along the node branch (for example, position 0 is exactly at the start of node branch, position 0.5 is in the middle, and position 1 is at the end).
Text labels
Template file: dataset_text_template.txt
Supported in the iTOL annotation editor for spreadsheets
In text label datasets, each node is associated to a single text label, which can be displayed directly on the node branch, or outside the tree.
For each label, exact position, color, font style, size factor and degree of rotation can be specified.
External labels can be aligned to the tree, in both circular and normal display mode. This will ignore any other rotation parameters.
Labels are normally rotated to match the current tree rotation. Straight labels option will make all labels appear straight ( or rotated by their individual rotation angles), regardless of the current tree rotation.
Internal labels can be displayed above or below the branches, and shifted vertically be any amount of pixels. By using this feature, multiple labels can be assigned to a branch (through separate datasets).
Branch and label styles
Template file: dataset_styles_template.txt
Supported in the iTOL annotation editor for spreadsheets
This dataset type allows the customization of display styles for tree branches and leaf labels. It copies the functionality of TREE_COLORS template file, but acts as a dataset. Therefore, multiple separate styles datasets can be present on a tree, and you can switch between various branch/label styles interactively. If multiple styles datasets are turned on simultaneously, only the last one will be applied.
Style definitions can be applied to single nodes/labels, or to whole clades. Check the template file for details.
Colored strips
Template file: dataset_color_strip_template.txt
Supported in the iTOL annotation editor for spreadsheets
In colored strip datasets, each node is associated to a color box/strip and can have an optional label. Similar to all other color definitions in iTOL, color can be specified in hexadecimal, RGB or RGBA notation (if transparency is required).
Each colored strip can have a border of varying width and color.
By using the COLOR_BRANCHES option, the colors of tree branches will match the colored strips above them. Ancestral branches whose children have identical colors will be colored as well, propagating the branch coloring towards the root of the tree.
Colored gradients
Template file: dataset_gradient_template.txt
Supported in the iTOL annotation editor for spreadsheets
In colored gradient datasets, each node is associated to a single numeric value, which is mapped to a colored box. Dataset values are mapped to a color gradient defined in the annotation file (fields COLOR_MIN, COLOR_MAX and optionally COLOR_MID), and can be later changed through the dataset options tab of the controls box.
Each colored gradient can have a border of varying width and color.
Connections
Template file: dataset_connections_template.txt
Supported in the iTOL annotation editor for spreadsheets
Connections datasets allow the drawing of straight or curved lines between any two nodes in the tree. Width, color, style (normal or dashed) and opacity can be set for each line. Optionally, arrow heads can be displayed on the lines.
Connection lines will be straight by default, and the curvature angle can be adjusted through CURVE_ANGLE option.
Connections within a single node (ie. where source and destination nodes are the same) are displayed as loops, whose size can be set through the LOOP_SIZE option.
Heatmaps
Template file: dataset_heatmap_template.txt
Supported in the iTOL annotation editor for spreadsheets
In heatmap datasets, each node is associated to multiple numeric values, which are displayed as a set of colored boxes. Dataset values are mapped to a color gradient defined in the annotation file (fields COLOR_MIN, COLOR_MAX and optionally COLOR_MID), and can be later changed.
Individual fields are defined in FIELD_LABELS, which will be displayed above the color matrix. Optionally, an additional Newick formatted tree can be specified using FIELD_TREE. If present, this tree will be displayed above the dataset labels, and will be used to define the order of the fields in the matrix.
Empty data fields can be specified using the letter 'X' instead of the numeric value. These will be colored using a separate color, defined using the option COLOR_NAN.
Boxplots (box and whisker diagrams)
Template file: dataset_boxplot_template.txt
Box plots (box and whisker diagrams) display the distribution of data based on the five number summary: minimum, first quartile, median, third quartile, and maximum. In addition to a box plot, each node can have an unlimited number of extremes defined, which will be displayed as crosses.
Protein domains
Template file: dataset_protein_domains_template.txt
Supported in the iTOL annotation editor for spreadsheets
Protein domain datasets are visualized as schematic representations of proteins, with a protein backbone and various shapes depicting the locations of individual domains. Even though its primary use is for the display of protein domains, it can be used for various other purposes.
Each node can have one protein definition assigned, with total protein length defined in second field, followed by an unlimited number of domain definitions. Each domain definition consists of 5 parts, separated with vertical lines:
SHAPE|START|END|COLOR|LABEL
Domain shape codes are as follows:
Code | Shape | Example |
---|---|---|
RE | rectangle | ![]() |
HH | horizontal hexagon | ![]() |
HV | vertical hexagon | ![]() |
EL | ellipse | ![]() |
DI | rhombus (diamond) | ![]() |
TR | right pointing triangle | ![]() |
TL | left pointing triangle | ![]() |
PL | left pointing pentagram | ![]() |
PR | right pointing pentagram | ![]() |
PU | up pointing pentagram | ![]() |
PD | down pointing pentagram | ![]() |
OC | octagon | ![]() |
GP | rectangle (gap) | ![]() |

Example protein domain architecture dataset, exported from SMART.
'Shape' plots
Template file: dataset_external_shapes_template.txt
Supported in the iTOL annotation editor for spreadsheets
In shape plots, each node has multiple numeric values associated with it. Values will be displayed as geometric shapes of different sizes in consecutive columns outside the tree. Highest value in the dataset will have the largest size, and all others will be scaled down proportionally.
Labels and colors for each column are defined in FIELD_LABELS and FIELD_COLORS. Optionally, a grid can be rendered behind the columns and the actual values can be displayed above the shapes. The shapes can be either filled with the defined colors, or displayed as outlines.
Shape is defined in SHAPE_TYPE, with a number between 1 and 5, but it can also be changed through the dataset options control tab.
1 | square | ![]() |
2 | circle | ![]() |
3 | star | ![]() |
4 | right triangle | ![]() |
5 | left triangle | ![]() |
Branch symbols
Template file: dataset_symbols_template.txt
Supported in the iTOL annotation editor for spreadsheets
Symbol datasets allow the display of various shapes directly on the branches of the tree. For each node, one or more symbols can be defined. Each symbol's color, size and position along the branch can be specified. Symbols can be filled with color, or drawn as outlines.
Symbols are defined as numbers between 1 and 5:
1 | square | ![]() |
2 | circle | ![]() |
3 | star | ![]() |
4 | right triangle | ![]() |
5 | left triangle | ![]() |
6 | checkmark | ![]() |
Phylogenetic placements
Template file: none, created automatically from .jplace files
iTOL supports the visualization of .jplace files created by pplacer and RAxML. Simply upload a .jplace file as a any other tree. Note that the file extension must be .jplace, otherwise the file will not be correctly recognised. iTOL will visualize the Newick tree contained in the file, and the phylogenetic placement information will be extracted as a separate dataset. Summary of placements will be automatically created, and can be visualized in various ways by changing the Summary type in the Datasets tab of the main control box.
When summaries are displayed as symbols, click any symbol to display a full list of sequences mapped to it. Clicking on a sequence name will highlight all other branches where it was placed.
Individual sequences can be searched and highlighted through the Query placements form. In the search results list, simply click any sequence to highlight its placement positions. Highlight symbols will be positioned according to distal_length and sized according to like_weight_ratio. Multiple sequences can be highlighted at the same time, using different symbols and colors. Use the Clear highlights button to remove all highlights from the tree.
MEME motifs
Template file: none, created automatically from MEME suite .xml files
iTOL supports the visualization of .xml files created by the MEME suite. Simply drag and drop a MEME .xml result file onto a tree. Note that the tree leaf IDs must match the sequence IDs in the MEME results.
Motifs will be visualized similarly to the 'Motif Locations' section of the MEME HTML output files. If strand information is present, motifs will be visualized above and below the backbone line, depending on their strand.
Hover over any motif to display a popup window with basic information about it, including the sequence and other details. Click on any motif to switch between the simple box representation and the motif logo display. You can increase the height of the motif logo display through the dataset settings, so it spans both strands instead of just one.
Multiple sequence alignments
Template file: dataset_alignment_template.txt
This dataset type allows the visualization of multiple sequence alignments directly next to the tree. The alignment should be in FASTA format, and must be placed below the DATA keyword in the template file. Consensus sequence (at 50% conservation) and residue conservation will be calculated automatically.
In addition to the most common alignment coloring schemes, it is possible to define custom schemes through the 'CUSTOM_COLOR_SCHEME' option in the dataset template. Multiple custom color schemes can be defined, and they will all be listed in the color scheme selection box in the dataset control tab.
Displaying large alignments (sequences with more than 1000 - 2000 residues) will severely impact performance, please be patient when manipulating the tree display. Due to internal browser limits, alignments blocks that can be displayed are limited to approximately 4000 residues.
Line charts
Template file: dataset_linechart_template.txt
Use this dataset template to visualize line charts. Each node in the tree is associated with a series of points, defined with their X and Y coordinates. Line charts can be displayed horizontally or vertically next to the nodes. To increase the spacing between the tree leaves (and make more space available for the charts), use the tree Scaling factors on the Advanced controls tab.
Custom axes grids can be defined through fields AXIS_X and AXIS_Y. Each line's color and width can be separately defined. AXIS_X will draw horizontal lines (i.e. values correspond to Y values), while AXIS_X will draw vertical lines (i.e. values correspond to X values)
Each line chart can be displayed using dots, lines or both. Default colors for dots and lines can be defined separately.
In addition, a series of color ranges can be defined using the field LINE_COLORS (see below). Each range consists of a Y value and the color, separated using a vertical line. For each point in the dataset, the first LINE_COLORS color whose value is above the point's Y value will be used to color the dot and line extending from it
In the example below, Y value of -10 would correspond to red (#ff0000), Y value of 2 would be black (#000000) and a value of 10 would be green (#00ff00)
LINE_COLORS -4|#ff0000 4|#000000 100|#00ff00
Images
Template file: dataset_image_template.txt
Use this dataset template to display various external images on the tree. Each node in the tree can be associated with an bitmap (any format supported by your browser) or vector image (SVG).
Images can be displayed internally on the tree branches, or outside the tree. In addition, each image's scale and position can be individually adjusted.
Image URL has to be specified in full (including the protocol, e.g. http://), and the images have to be accessible via that URL by your browser. They are not accessed by iTOL directly, unless you export the tree using batch mode.
Tree management and user account
Check our tree management video tutorial.
Creating an account in iTOL gives you the possibility to easily organize your trees and have an overview of their features, datasets and saved views. Trees are grouped into different projects, and these can be arranged into different workspaces.
Configuration and functions can be accessed by clicking the icons in the corner of project boxes, in the workspace tab bar and at the end of each tree table row.
Working with projects and workspaces:
- Add/delete a workspace or a project through the functions menus ()
- Click the workspace label and drag it to rearrange workspace order
- Click the workspace or project descriptions to edit them
- Double click project title bars to collapse/uncollapse projects
- Click and drag the project title to rearrange projects
- Click and drag the project title to a different workspace tab label to move the project there
To upload trees to a project, you can use the button in the project box, or simply drag and drop one or more tree files to the project footer.
Creating figures and tree export
Use the Export tab of the control box to export the current tree into vector or bitmap figures. Depending on the setting selected, it can take a few minutes until the figures are generated.
If you use the exported figures in a publication, please cite one of iTOL publications.
Batch access
iTOL supports batch tree upload and export through a simple CGI interface. We are providing it for advanced users who want to upload or export their trees directly from other scripts/programs. Please be considerate to other users if you're using this method to access iTOL. Make sure to wait at least a few seconds between requests, particularly if exporting to PNG.
Example uploader and downloader Perl scripts are available for download. You can use the example data archive for testing the uploader script.
Batch upload
https://itol.embl.de/batch_uploader.cgi
iTOL batch uploader is a standard CGI script, available at https://itol.embl.de/batch_uploader.cgi. Use a standard POST request to submit your data. Available parameters are described below. Script will produce plain text output (Content-type text/plain), as follows:
- An error occurred during upload: first line will start with the keyword ERR, followed by a numeric error code and longer description
- Upload was successful, without warnings: first line will start with the keyword SUCCESS:, followed by a space character and the iTOL tree ID
- Upload was successful, warnings occurred: warnings will be printed one per line, and the last line will start with the keyword SUCCESS:, followed by a space character and the iTOL tree ID If your upload was successful, store the returned iTOL tree ID for further use.
Batch uploader options
Required parameters
- zipFile
-
a ZIP archive containing the tree and all other dataset and annotation files. Your tree file must have the extension .tree or .tree.txt. All other files can be named as you wish. When the files are processed during upload , they will be sorted by name, allowing you to order the datasets (if required).
- APIkey
- Your API key, which can be generated through your user account options menu (while logged in, click your name in the top right corner of any page to access the option).
- projectName
- Project name is case sensitive, and should be unique in your account. We recommend creating a separate project for batch uploaded trees.
Optional parameters
- treeName
- If treeName is not provided, the tree file name will be used instead.
- treeDescription
- If provided, the description will be shown in your account page
Batch download
https://itol.embl.de/batch_downloader.cgi
iTOL batch downloader is a standard CGI script, available at https://itol.embl.de/batch_downloader.cgi. Use a standard POST or GET request when submitting your download parameters. Available parameters are described below. The script will generate output as follows:
- An error occurred during export: Output will in Content-type: text/html, and the error will be printed.
- Export was successful: Output will be in the Content-type matching your selected format (image/svg+xml for SVG, image/png for PNG, application/postscript for PS and EPS and application/pdf for PDF). Make sure your downloader handles the incoming binary data properly.
Batch download parameters
These are the available options, and their supported values:
Required parameters
- tree
-
iTOL tree ID which will be exported
- format
- Output file format. The following values are supported:
- Graphical formats: svg, eps, pdf and png
- Text formats: newick, nexus and phyloxml
Optional parameters
If you don't specify one of the optional parameters, values which are saved as defaults for the tree will be used (or standard defaults, if none were saved). Apart from newick_format, all parameters are used only during export to graphical formats. If you require an option which available in the iTOL web interface, but is missing from the list below, contact us.
- newick_format
- Possible value: ID. Only used when export format is set to newick. If specified, internal node IDs will be included in exported Newick trees.
- display_mode
- Possible values: 1,2 or 3 (1=normal, 2=circular, 3=unrooted)
- tree_x
- Tree will be shifted horizontally by this value, positive or negative (value in pixels)
- tree_y
- Tree will be shifted vertically by this value, positive or negative (value in pixels)
- vertical_shift_factor
- Vertical tree scaling factor (positive number)
- horizontal_scale_factor
- Horizontal tree scaling factor (positive number)
- current_font_size
- Main label font size in pixels (integer >= 9)
- current_font_name
- Possible values: 'Arial', 'Courier', 'Courier New', 'Verdana', 'Impact', 'Georgia', 'Times New Roman' or 'Monotype Corsiva'
- current_font_style
- Possible values: 'normal', 'bold' or 'bold italic'
- leaf_sorting
- Possible values: 1 or 2 (1=normal sorting, 2=no sorting)
- label_display
- Possible values: 0 or 1 (0=hide labels, 1=show labels)
- align_labels
- Possible values: 0 or 1 (0=labels not aligned, 1=labels aligned)
- label_shift
- Amount to shift the leaf labels (positive or negative, in pixels)
- dashed_lines
- Display dashed lines connecting branches to leaf labels. Possible values: 0 or 1 (0=hide lines, 1=display lines)
- ignore_branch_length
- Possible values: 0 or 1
- slanted_normal
- Display tree in slanted (triangular) mode. Possible values: 0 or 1. If set to 1, note that both display_mode and ignore_branch_length must also be set to 1.
- arc
- Angle of the display arc for the circular tree (in degrees, a number between 0 and 360)
- rotation
- Rotation angle for circular tree (in degrees, a number between 0 and 360)
- normal_rotation
- Rotation angle for normal tree (in degrees, a number between 0 and 360)
- unrooted_rotation
- Rotation angle for unrooted tree (in degrees, a number between 0 and 360)
- line_width
- Width of tree lines (in pixels)
- line_gradient
- Is set to '1', branch color will be a gradient between ancestor and node color.
- default_branch_color
- Default color of tree's branches (hex, RGB or RGBA notation)
- default_label_color
- Default color of tree's labels (hex, RGB or RGBA notation)
- inverted
- Inverted display (only for circular and normal mode). Possible values: 0 or 1
- circle_size_inverted
- For inverted circular display only. Internal radius will be increased by this amount (value in pixels)
- range_mode
- Colored ranges display style. Possible values: 0,1 or 2 (0=off, 1=cover labels only, 2=cover full clades)<
- include_ranges_legend
- Include colored ranges legend. Possible values: 0 or 1
- ranges_legend_title
- Title of the colored ranges legend.
- internal_marks
- Draw circles to mark the location of internal nodes. Possible values: 0, 1 or 2 (0=Do not display, 1=Display on nodes with one child, 2=Display always)
- internal_scale
- Draw internal tree scale. All internal scale settings below are only used if this is set to 1. Possible values: 0 or 1
- internal_scale_inverted
- Invert the internal tree scale (start at the farthest leaf instead of root). Possible values: 0 or 1
- internalScaleRootValue
- Set the time/number value for the tree root. All scale labels will be calculated from this number and the internalScaleTimeScaling value
- internalScaleTimeScaling
- Multiply all branch length values by this number when displaying scale labels.
- internalScaleAxis
- Draw internal tree scale axis. Possible values: 0 or 1
- internalScaleGrid
- Draw internal tree scale grid. Possible values: 0 or 1
- internalScaleFontSize
- Font size for internal scale labels (in px)
- internalScale1
- Repeat value for the first set of internal scale lines (branch length value)
- internalScale2
- Repeat value for the second set of internal scale lines (branch length value)
- internalScaleFixed
- Comma delimited list of fixed values (branch length) where lines should be drawn
- internalScale1Color
- Color for the first set of internal scale lines (hex, RGB or RGBA)
- internalScale2Color
- Color for the second set of internal scale lines (hex, RGB or RGBA)
- internalScaleFixedColor
- Color for the fixed position internal scale lines (hex, RGB or RGBA)
- internalScale1Label
- Draw labels on the first set of grid lines. Possible values: 0 or 1
- internalScale2Label
- Draw labels on the second set of grid lines. Possible values: 0 or 1
- internalScaleFixedLabel
- Draw labels on the fixed position grid lines. Possible values: 0 or 1
- internalScale1Dashed
- First set of grid lines will be dashed. Possible values: 0 or 1
- internalScale2Dashed
- Second set of grid lines will be dashed. Possible values: 0 or 1
- internalScaleFixedDashed
- Fixed position grid lines will be dashed. Possible values: 0 or 1
- internalScale1Wid
- Line width for the first set of internal scale lines (in px)
- internalScale2Wid
- Line width for the second set of internal scale lines (in px)
- internalScaleFixedWid
- Line width for the fixed position internal scale lines (in px)
- branchlength_display
- Display branch length text labels on branches (possible values: 0 or 1)
- branchlength_label_size
- Font size for the branch length labels (in pixels, integer >= 0)
- branchlength_label_position
- Position of the branch length labels along the branch (in percent, default is 50%)
- branchlength_label_sci
- Display branch length labels in scientific notation (if set to 1)
- branchlength_label_rounding
- Round branch length labels to this number of decimals (integer >= 0)
- branchlength_label_age
- Display node age instead of raw branch length values (if set to 1)
- metadata_source
- Which metadata source to use for bootstrap display options (default: 'bootstrap', other possible options depend on the data in the tree)
- bootstrap_display
- Display metadata values (possible values: 0 or 1)
- bootstrap_type
- Type of metadata display. Possible values: 1, 2, 3 or 4 (1=Symbol, 2=Text label, 3=Branch color and 4=Branch width
- bootstrap_symbol
- Symbol used to display metadata values. Possible values: 1, 2, 3 or 4 (1=Circle, 2=Triangle, 3=Square and 4=Star)
- bootstrap_symbol_min
- Minimum size for the metadata symbol (in pixels)
- bootstrap_symbol_max
- Maximum size for the metadata symbol (in pixels)
- bootstrap_symbol_position
- Position of the metadata symbol along the branch (in percent, default is 50%)
- bootstrap_symbol_color
- Bootstrap symbol color (hex, RGB or RGBA)
- bootstrap_slider_min
- Minimum metadata value to display
- bootstrap_slider_max
- Maximum metadata value to display
- bootstrap_label_position
- Position of the metadata text label along the branch (in percent, default is 50%)
- bootstrap_label_size
- Font size for the metadata text labels (in pixels, integer >= 9)
- bootstrap_label_sci
- Display metadata labels in scientific notation (if set to 1)
- bootstrap_label_rounding
- Round metadata labels to this number of decimals (integer >= 0)
- bootstrap_width_min
- Branch width for minimum metadata value (in pixels), when bootstrap_type=4
- bootstrap_width_max
- Branch width for maximum metadata value (in pixels), when bootstrap_type=4
- bootstrap_min_color
- Branch color for minimum metadata value (hex, RGB or RGBA), when bootstrap_type=3
- bootstrap_use_mid_color
- Use a three color gradient for metadata branch colors (possible values: 0 or 1)
- bootstrap_mid_color
- Branch color for midpoint metadata value (hex, RGB or RGBA), when bootstrap_type=3 and bootstrap_use_mid_color=1
- bootstrap_max_color
- Branch color for maximum metadata value (hex, RGB or RGBA), when bootstrap_type=3
- datasets_visible
- Comma delimited list of datasets to display (starting with 0, e.g. datasets_visible=0,2,5)
External tools
A selection of iTOL related external tools / helper scripts:
- iTOL annotation editor: access your iTOL trees, create and edit datasets directly in Microsoft Excel
- phyloT: a tree generator based on NCBI taxonomy which can visualize trees directly in iTOL
- table2itol: an R script that makes it easy to generate iTOL annotations from spreadsheet files
- Gotree: GoTree is a set of command line tools to manipulate phylogenetic trees, implemented in Go language.
- itolAPI: phyton API for iTOL batch access.
Please contact the authors of these tools directly if you encounter any issues.