How to Add Text Labels to Your Vega-Lite Visualizations

Adding text labels to your visualizations is essential for making your data more accessible and informative. Vega-Lite provides powerful text mark capabilities that allow you to label data points, annotate charts, and add context directly to your visualizations.

Why Use Text Labels?

Text labels serve several important purposes in data visualization:

• Direct labeling: Show exact values on bars, points, or other marks
• Annotations: Highlight important insights or outliers
• Context: Add units, percentages, or explanatory text
• Accessibility: Make charts readable without relying solely on axes or legends

Basic Text Marks

The simplest way to add labels in Vega-Lite is using the text mark type:

Combining Text with Other Marks

You can layer text marks on top of other marks to create labeled visualizations:

Bar Chart with Value Labels

Scatter Plot with Point Labels

Text Mark Properties

You can customize text appearance using various properties:

• dx / dy: Offset text horizontally/vertically
• align: Text alignment (left, center, right)
• baseline: Vertical alignment (top, middle, bottom)
• fontSize: Text size
• fontWeight: Bold, normal, or numeric values
• angle: Rotation angle in degrees

Example: Customized Text Labels

Advanced Labeling Techniques

Conditional Labels

Show labels only for specific data points:

Multi-line Labels

Create labels with multiple lines of text:

Best Practices for Text Labels

1. Keep it concise: Use short, clear labels that don't clutter the visualization
2. Use formatting: Apply number formatting for readability (e.g., "1.2k" instead of "1234")
3. Consider contrast: Ensure text is readable against the background
4. Strategic placement: Use dx and dy to avoid overlapping with data marks
5. Selective labeling: Label only the most important points to avoid overcrowding

Common Use Cases

Percentage Labels on Pie Charts

When using arc marks, you can add percentage labels:

Annotations

Add explanatory text to highlight insights:

FAQ

How do I prevent text labels from overlapping?

Use the labelOverlap config or apply transforms to filter overlapping labels. You can also adjust dx and dy properties or use conditional encoding to show fewer labels.

Can I use different fonts for labels?

Yes, you can specify font in the text mark properties or in the config. Make sure the font is available in the viewer's system.

How do I format numbers in text labels?

Use the format property in the text encoding. For example: "format": ",.0f" for thousands separators or "format": ".2%" for percentages.

Can I make labels interactive?

Text marks can respond to selections and conditions just like other marks. You can change opacity, color, or size based on interactions.

Start enhancing your Vega-Lite visualizations with meaningful text labels today!