> ## Documentation Index
> Fetch the complete documentation index at: https://logo-soup.sanity.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# jQuery
> Use Logo Soup with jQuery 4.x via the $.fn.logoSoup plugin.
## Install
```bash theme={null}
npm install @sanity-labs/logo-soup jquery@4
```
Requires jQuery 4.0 or later.
## Setup
The plugin needs to be installed onto jQuery. There are two ways to do this:
### Auto-install (global jQuery)
If jQuery is available on `window`, the plugin installs itself automatically on import:
```html theme={null}
```
### Manual install (ES modules)
When using a bundler, import and call `install` with your jQuery instance:
```ts theme={null}
import $ from "jquery";
import { install } from "@sanity-labs/logo-soup/jquery";
install($);
```
## Basic Usage
```ts theme={null}
$("#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: 28,
alignBy: "visual-center-y",
});
```
The plugin renders normalized `` elements into the selected container with visual center alignment and a fade-in transition.
## Plugin Options
All [shared options](/docs/options) are supported, plus these jQuery-specific ones:
| Option | Type | Default | Description |
| --------- | ----------------------------------- | ------------------- | ------------------------------------- |
| `alignBy` | `AlignmentMode` | `"visual-center-y"` | How to align logos |
| `gap` | `number \| string` | `28` | Space between logos |
| `onReady` | `(logos: NormalizedLogo[]) => void` | — | Callback when normalization completes |
| `onError` | `(error: Error) => void` | — | Callback when all images fail to load |
## Methods
Call methods on an existing plugin instance using the standard jQuery plugin convention:
### `process`
Update the logos or options on an existing instance:
```ts theme={null}
$("#logos").logoSoup("process", {
logos: ["/logos/new-logo.svg", "/logos/another.svg"],
baseSize: 64,
});
```
### `ready`
Returns a native `Promise` that resolves with the normalized logos when processing completes:
```ts theme={null}
const logos = await $("#logos").logoSoup("ready");
console.log(logos.length, "logos normalized");
```
If logos are already processed, the promise resolves immediately. If processing fails, the promise rejects with the error.
### `destroy`
Removes the plugin instance, cleans up the engine, and empties the container:
```ts theme={null}
$("#logos").logoSoup("destroy");
```
### `instance`
Returns the internal plugin instance (engine, unsubscribe function, current options) for the first matched element. Useful for advanced use cases:
```ts theme={null}
const instance = $("#logos").logoSoup("instance");
const state = instance.engine.getSnapshot();
```
## Full Example
```html theme={null}
```
## Dark Mode
Pass `backgroundColor` for proper contrast detection on opaque logos:
```ts theme={null}
const isDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
$("#logos").logoSoup({
logos,
backgroundColor: isDark ? "#1a1a1a" : "#ffffff",
});
```
## Chaining
The plugin supports standard jQuery chaining for initialization, `process`, and `destroy`:
```ts theme={null}
$("#logos")
.logoSoup({ logos, baseSize: 48 })
.addClass("logo-strip")
.css("padding", "20px");
```
The `ready` method breaks the chain since it returns a `Promise` instead of a jQuery object.
## Re-initialization
Calling `.logoSoup({...})` on an element that already has an instance automatically destroys the old instance and creates a new one:
```ts theme={null}
// First init
$("#logos").logoSoup({ logos: firstLogos });
// Re-init with different logos — old engine is cleaned up
$("#logos").logoSoup({ logos: secondLogos });
```
## How It Works Under the Hood
The jQuery adapter is a standard `$.fn` plugin that:
* Stores the engine instance via `$.data()` on each element
* Subscribes to the engine's state changes and renders `` elements into the container using DOM APIs
* Applies `getVisualCenterTransform` for visual center alignment
* Uses native `Promise` for the `ready` method (jQuery 4 slim build dropped Deferreds in favor of native Promises)
* Cleans up blob URLs and subscriptions on `destroy`