Skip to main content

​
What is Logo Soup?

Logo Soup is a framework-agnostic library that solves the “logo soup” problem—when you display multiple company logos together, they often look chaotic due to different sizes, weights, aspect ratios, and visual density.

Before

Logos with different sizes, weights, and aspect ratios create visual chaos

After

The same logos appear balanced and harmonious with proper normalization

​
The Problem

When displaying logos from different brands, you typically encounter:
  • Inconsistent aspect ratios — Some logos are wide, others are tall, creating awkward spacing
  • Visual weight differences — Bold, dense logos overpower thin, light logos even when physically the same size
  • Embedded whitespace — Many logos have padding baked into the image file, making alignment difficult
  • Optical illusions — Light logos on dark backgrounds appear larger than they actually are (Helmholtz irradiation)
Read the full deep-dive: The Logo Soup Problem (and how to solve it)

​
The Solution

Logo Soup analyzes each logo and automatically:
  1. Detects true content boundaries — Ignores whitespace and padding baked into the image
  2. Normalizes aspect ratios — Balances wide vs tall logos using a configurable scale factor
  3. Compensates for density — Adjusts sizing so dense logos don’t overpower light ones
  4. Handles irradiation — Corrects for optical illusions on dark backgrounds
All processing happens client-side using canvas. No server, no AI, fully deterministic.

​
Key Features

Framework Agnostic

Works with React, Vue, Svelte, Solid, Angular, jQuery, and vanilla JavaScript

Tiny Bundle Size

Core engine is lightweight with tree-shakeable framework adapters

Client-Side Processing

All analysis happens in the browser using canvas—no server required

Highly Configurable

Control size, density compensation, cropping, alignment, and more

​
Architecture Overview

Logo Soup is built as a single package with subpath exports: 
@sanity-labs/logo-soup          → Core engine, types, utilities, constants
@sanity-labs/logo-soup/react    → useLogoSoup hook + LogoSoup component
@sanity-labs/logo-soup/vue      → useLogoSoup composable
@sanity-labs/logo-soup/svelte   → createLogoSoup (runes-compatible)
@sanity-labs/logo-soup/solid    → useLogoSoup primitive
@sanity-labs/logo-soup/angular  → LogoSoupService (Injectable)
@sanity-labs/logo-soup/jquery   → $.fn.logoSoup plugin

​
Core Engine

The core createLogoSoup() engine handles all:
  • Image loading and measurement
  • Content boundary detection
  • Normalization calculations
  • Caching and optimization
  • Cancellation and cleanup
Each framework adapter is a thin wrapper (30-80 lines) that bridges the engine’s subscribe/getSnapshot interface into the framework’s reactivity model.
Tree-shaking ensures a React consumer never pulls in Vue/Svelte/Solid/Angular code, keeping your bundle minimal.

​
How It Works

1

Content Detection

Analyzes each logo on a downscaled canvas to find true content boundaries, ignoring whitespace and padding baked into the image
2

Aspect Ratio Normalization

Applies a configurable scaleFactor to balance wide vs tall logos (0 = uniform widths, 1 = uniform heights, 0.5 = balanced)
3

Density Compensation

Measures the pixel density (visual weight) of each logo and adjusts sizing so dense/bold logos don’t overpower light/thin ones
4

Irradiation Compensation

Adjusts for the Helmholtz irradiation illusion where light content on dark backgrounds appears larger than it is

​
Next Steps

Quickstart

Get up and running in 5 minutes

React Guide

Deep dive into React usage

Configuration

Explore all options and alignment modes

Core API

Use the vanilla engine directly

Build docs developers (and LLMs) love

Get started for freeTalk to us