Installation
npm install @sanity-labs/logo-soup jquery@^4
Supports jQuery 4.x. Auto-installs onto window.jQuery if available.
Quick Start
Install the plugin, then call .logoSoup() on any jQuery selection:
import $ from "jquery";
import { install } from "@sanity-labs/logo-soup/jquery";
install($);
$("#logos").logoSoup({
logos: [
{ src: "/logos/acme.svg", alt: "Acme Corp" },
{ src: "/logos/globex.svg", alt: "Globex" },
{ src: "/logos/initech.svg", alt: "Initech" },
],
baseSize: 48,
alignBy: "visual-center-y",
});
Plugin API
Installation
import $ from "jquery";
import { install } from "@sanity-labs/logo-soup/jquery";
install($);
window.jQuery exists, the plugin auto-installs.
Initialization
$(selector).logoSoup(options);
| Option | Type | Default | Description |
|---|
logos | (string | LogoSource)[] | required | Array of logo URLs or objects |
baseSize | number | 48 | Target size in pixels |
scaleFactor | number | 0.5 | Shape handling balance |
densityAware | boolean | true | Scale dense logos |
densityFactor | number | 0.5 | Density effect strength |
cropToContent | boolean | false | Crop whitespace |
contrastThreshold | number | 10 | Content detection threshold |
backgroundColor | string | [r,g,b] | auto | Background color hint |
alignBy | AlignmentMode | "visual-center-y" | Alignment mode |
gap | number | string | 28 | Space between logos |
onReady | (logos) => void | - | Callback when ready |
onError | (error) => void | - | Error callback |
Methods
Update Logos
$("#logos").logoSoup("process", { logos: newLogos });
Wait for Ready
const logos = await $("#logos").logoSoup("ready");
console.log("Loaded", logos.length, "logos");
Uses native Promise (not jQuery Deferred) to support jQuery 4 slim builds.
Destroy
$("#logos").logoSoup("destroy");
Get Instance
const instance = $("#logos").logoSoup("instance");
if (instance) {
const state = instance.engine.getSnapshot();
}
Examples
Basic Usage
Dynamic Updates
Async Ready
With Callbacks
import $ from "jquery";
import { install } from "@sanity-labs/logo-soup/jquery";
install($);
$("#logos").logoSoup({
logos: [
{ src: "/logos/acme.svg", alt: "Acme Corp" },
{ src: "/logos/globex.svg", alt: "Globex" },
{ src: "/logos/initech.svg", alt: "Initech" },
],
baseSize: 48,
gap: 32,
alignBy: "visual-center-y",
});
import $ from "jquery";
import { install } from "@sanity-labs/logo-soup/jquery";
install($);
// Initialize
$("#logos").logoSoup({
logos: ["/logo1.svg", "/logo2.svg"],
});
// Later, update logos
$("#add-logo").on("click", () => {
const currentLogos = [/* ... get current logos ... */];
const newLogos = [...currentLogos, "/new-logo.svg"];
$("#logos").logoSoup("process", { logos: newLogos });
});
// Clean up
$("#clear").on("click", () => {
$("#logos").logoSoup("destroy");
});
import $ from "jquery";
import { install } from "@sanity-labs/logo-soup/jquery";
install($);
async function loadLogos() {
$("#logos").logoSoup({
logos: ["/logo1.svg", "/logo2.svg", "/logo3.svg"],
baseSize: 64,
});
try {
const logos = await $("#logos").logoSoup("ready");
console.log(`Successfully loaded ${logos.length} logos`);
logos.forEach((logo) => {
console.log(`${logo.alt}: ${logo.normalizedWidth}x${logo.normalizedHeight}`);
});
} catch (error) {
console.error("Failed to load logos:", error);
}
}
loadLogos();
import $ from "jquery";
import { install } from "@sanity-labs/logo-soup/jquery";
install($);
$("#logos").logoSoup({
logos: [
{ src: "/logos/acme.svg", alt: "Acme Corp" },
{ src: "/logos/globex.svg", alt: "Globex" },
],
baseSize: 48,
onReady: (logos) => {
console.log("Logos normalized:", logos);
$("#loading").hide();
$("#logos").fadeIn();
},
onError: (error) => {
console.error("Failed to normalize:", error);
$("#error").text(error.message).show();
},
});
Data Attributes
The plugin sets data-logo-soup-loading on the container element:
<div id="logos" data-logo-soup-loading="true"><!-- logos --></div>
#logos[data-logo-soup-loading="true"] {
opacity: 0;
}
#logos[data-logo-soup-loading="false"] {
opacity: 1;
transition: opacity 0.3s;
}
Instance Storage
The plugin stores instance data using $.data():
const instance = $.data(element, "logoSoup");
// { engine, unsubscribe, options }
Chaining
All methods return the jQuery object for chaining:
$("#logos")
.logoSoup({ logos: ["/logo1.svg"] })
.addClass("active")
.fadeIn();
TypeScript
The plugin extends jQuery’s type definitions:
import type {
LogoSoupPluginOptions,
} from "@sanity-labs/logo-soup/jquery";
import type {
LogoSource,
NormalizedLogo,
AlignmentMode,
} from "@sanity-labs/logo-soup";
declare global {
interface JQuery {
logoSoup(options: LogoSoupPluginOptions): JQuery;
logoSoup(method: "process", options: ProcessOptions): JQuery;
logoSoup(method: "destroy"): JQuery;
logoSoup(method: "ready"): Promise<NormalizedLogo[]>;
logoSoup(method: "instance"): LogoSoupInstance | undefined;
}
}
See Also