KPI Donut Chart - Looker Studio Community Visualization

A customizable KPI donut chart for Google Looker Studio. Displays a metric value in the center with a donut arc showing progress toward a goal, with optional icons and labels.

Features

• Customizable donut arc with configurable fill color, background color, and ring thickness
• Arc gap setting (0-240 degrees) for gauge-style appearance
• Center value formatting: Number, Currency (25 currencies), or Percentage
• Compact numbers: Optional K/M/B suffixes
• 60+ icons organized by category (status, trends, charts, finance, etc.)
• Conditional icons: Change icon and color based on value vs. threshold
• Tooltips: Hover on filled/remaining arc shows value and percentage
• Fully responsive: Scales to any container size

Quick Start

Prerequisites

• Node.js and npm installed
• Google Cloud SDK with gsutil configured
• A Google Cloud Storage bucket with public read access

Installation

1. Clone the repository

git clone https://github.com/YOUR_USERNAME/kpi-donut-chart.git
cd kpi-donut-chart

2. Install dependencies

npm install

3. Build the visualization

npm run build

This creates dist/viz.js - the bundled visualization file.

Deployment

1. Create a GCS bucket (if you don't have one)

gsutil mb gs://your-bucket-name

2. Make the bucket publicly readable

gsutil iam ch allUsers:objectViewer gs://your-bucket-name

3. Update manifest.json

Edit manifest.json and replace all occurrences of YOUR_BUCKET_NAME with your actual bucket name:

{
  "resource": {
    "js": "gs://your-bucket-name/viz.js",
    "config": "gs://your-bucket-name/config.json"
  }
}

4. Deploy the files

gsutil cp dist/viz.js gs://your-bucket-name/
gsutil cp config.json gs://your-bucket-name/
gsutil cp manifest.json gs://your-bucket-name/

Adding to Looker Studio

1. Open a Looker Studio report
2. Click "Community visualizations and components" in the toolbar
3. Click "Build your own visualization"
4. Enter the manifest path: gs://your-bucket-name/manifest.json
5. Click Submit

The visualization will now appear in your community visualizations panel.

Data Configuration

Field	Required	Description
Display Value	Yes	The number shown in the center (formatted)
Actual Value	Yes	The value used for donut fill calculation
Total/Max Value	Yes	The denominator (100% = full donut)
Label	No	Text label shown below the value

Example: If Actual Value = 75 and Total Value = 100, the donut shows 75% filled.

Style Options

Donut Arc

• Fill Color
• Background Color (or transparent)
• Ring Thickness (4-40px)
• Arc Gap (0-240 degrees)

Center Value

• Number Format (Number, Currency, Percent)
• Currency Code (24 options)
• Decimal Places (Auto, 0-3)
• Font Size, Family, Color
• Compact Numbers (K/M/B)

Center Label

• Font Size, Family, Color
• Static Label Text (overrides dimension)

Icons

• Show/Hide Icon
• Icon Mode: Static or Conditional
• 60+ icon options
• Icon Size and Color
• Conditional thresholds with different icons/colors for above/below/equal

Tooltip

• Show/Hide Tooltip
• Content: Value Only, Percentage Only, or Both
• Custom labels for filled/remaining arcs
• Background and text colors

Icon Categories

• Status: Checkmark, Success, Warning, Alert, Info, Error, Question, Minus
• Trends: Arrow Up/Down/Right, Trending Up/Down, Activity
• Charts: Bar Chart, Pie Chart, Line Chart
• Metrics: Gauge, Target, Percent
• Finance: Dollar, Credit Card, Wallet, Coins
• Business: User, Users, Clock, Calendar, Briefcase, List
• Communication: Mail, Bell, Phone, Message
• Navigation: Home, Settings, Search, Globe, Bookmark
• Data: Database, Cloud, Folder
• Actions: Refresh, Download, Upload, Play, Pause
• Objects: Gift, Package, Truck
• Achievement: Star, Trophy, Medal, Crown, Award, Flag, Lightning, Battery, Rocket, Fire, Shield
• Feedback: Heart, Thumbs Up/Down
• Security: Lock, Eye

Development

Watch mode

npm run dev

This rebuilds automatically when you save changes.

Testing locally

After building, deploy to GCS and refresh your Looker Studio report (Ctrl+Shift+R).

Project Structure

kpi-donut-chart/
├── src/
│   ├── index.js      # Main visualization logic
│   └── icons.js      # SVG icon library (60+ icons)
├── dist/
│   └── viz.js        # Webpack bundle output
├── config.json       # Looker Studio style configuration
├── manifest.json     # Visualization manifest
├── package.json      # Node dependencies
├── webpack.config.js # Build configuration
└── .claude/
    └── skills/
        └── building-looker-studio-visualizations/  # Claude skill for building visualizations

Building Your Own Visualizations

This repository includes a Claude skill file (.claude/skills/looker-studio-viz.md) that helps you build new Looker Studio community visualizations using AI. The skill contains:

• Project structure templates
• config.json style element types
• Data access patterns
• SVG icon creation best practices
• Deployment commands
• Common issues and solutions

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

If you encounter issues or have questions:

1. Check the Issues page
2. Open a new issue with details about your problem

---

Built by Toufik | databytoufik.com