Foley

https://usefoley.dev/docs
Admin
Foley is a tiny, dependency-free library of interaction sound effects synthesized live with the Web...
Tokens:3,645
Snippets:54
Trust Score:2.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Run the Foley demo

Source: https://usefoley.dev/docs.html

Start a local server to view the demo page.

```bash
npm run demo        # or: npx serve .
```

--------------------------------

### Development commands

Source: https://usefoley.dev/docs.html

Standard commands for installing dependencies, running tests, and building the project.

```bash
npm install      # once per clone — the test suite imports the framework packages,
                 # which need react and the self-linked core from node_modules
npm test         # node --test: metadata integrity, settings, docs/types consistency, build
npm run build    # regenerate the single-file demo at dist/foley-demo.html
npm run docs     # render README.md into dist/docs.html (deployed at /docs.html)
npm run demo     # serve the demo locally
```

--------------------------------

### Quickstart Foley Implementation

Source: https://usefoley.dev/docs.html

Markup elements with data-foley attributes and initialize the library using the bind function.

```html
<button data-foley-press data-foley-release>Save</button>
<a data-foley-hover="tick">Docs</a>
<button data-foley-toggle aria-pressed="false">Dark mode</button>
<input data-foley-type="thock">
```

```javascript
import { bind, play, set } from "@foleyjs/core";

bind();                          // wires every data-foley-* attribute
set({ volume: 0.7, theme: "default" });

play("success");                 // programmatic cues for things the user didn't click
play("tick", { pitch: 4, volume: 0.3 });
```

--------------------------------

### Install FoleyJS Core

Source: https://usefoley.dev

Use the package manager of your choice to add the core library to your project.

```bash
npm install @foleyjs/core
```

--------------------------------

### Initialize Foley in React

Source: https://usefoley.dev/docs.html

Use the useFoley hook to initialize the framework with a specific theme.

```javascript
const { play } = useFoley({ theme: "soft" })
```

--------------------------------

### Apply a theme

Source: https://usefoley.dev/docs.html

Apply a predefined theme to globally reshape all 28 cues.

```javascript
set({ theme: "glass" }); // "default" | "soft" | "mechanical" | "glass"
```

--------------------------------

### set(settings)

Source: https://usefoley.dev/docs.html

Updates global audio settings including volume, theme, and localization.

```APIDOC
## set(settings)

### Description
Updates global engine settings. 

### Parameters
- **settings** (object) - Required - Settings object including `volume`, `transpose`, `space`, `muted`, `hover`, `theme`, `duck`, or `localize`.
```

--------------------------------

### play(cue, options)

Source: https://usefoley.dev

Triggers a sound cue with specific configuration options like pitch.

```APIDOC
## play(cue, options)

### Description
Plays a sound cue with additional configuration parameters to modify the audio output.

### Parameters
- **cue** (string) - Required - The identifier of the sound to play.
- **options** (object) - Optional - Configuration object.
  - **pitch** (number) - Optional - Adjusts the pitch of the sound.

### Example
play("tick", { pitch: 1.2 });
```

--------------------------------

### Progress feedback

Source: https://usefoley.dev

Plays a sequence of sounds to indicate loading and completion states.

```javascript
play("rise") → play("complete")
```

--------------------------------

### Import Foley.js Core

Source: https://usefoley.dev/docs.html

Import the necessary functions and constants from the @foleyjs/core package.

```javascript
import { play, bind, set, get, toWav, unlock, getAnalyser, on, cues, families, themes, version } from "@foleyjs/core";
```

--------------------------------

### unlock()

Source: https://usefoley.dev/docs.html

Resumes or creates the AudioContext following a user gesture.

```APIDOC
## unlock()

### Description
Must be called in response to a user gesture to initialize the browser's AudioContext.
```

--------------------------------

### bind(root)

Source: https://usefoley.dev/docs.html

Wires all data-foley-* attributes under the specified root element.

```APIDOC
## bind(root)

### Description
Initializes Foley.js functionality by binding to all `data-foley-*` attributes within the provided root element. Defaults to `document` if no root is provided.
```

--------------------------------

### set(theme)

Source: https://usefoley.dev/docs.html

Updates the active sound identity or applies a predefined theme.

```APIDOC
## set(theme)

### Description
Sets the product's sonic identity. Can accept a full configuration object or a string representing a built-in theme.

### Parameters
- **theme** (Object|String) - Required - Either a full configuration object containing name, transform, and cues, or a string identifier for a built-in theme (e.g., "default", "soft", "mechanical", "glass").
```

--------------------------------

### Positioning Audio Cues

Source: https://usefoley.dev/docs.html

Use pan for stereo field placement and pos for 3D spatialization. The localize setting allows bound cues to pan relative to their specific UI elements.

```javascript
play("tick", { pan: -0.7 });              // over on the left
play("ping", { pos: [1, 0, -0.5] });      // to the right, slightly in front
set({ localize: 0.6 });                   // every bound cue pans to its own button
```

--------------------------------

### Define and retrieve a sound set

Source: https://usefoley.dev/docs.html

Use set to define a global sonic identity and getSet to export the current configuration as a JSON-safe object.

```javascript
import { set, getSet } from "@foleyjs/core";

set({ theme: {
  name: "Acme",
  transform: { pitch: 0.9, decay: 1.3 },      // every cue, reshaped
  cues: { success: [/* layers */], error: [/* layers */] }  // these two, replaced
}});

get().theme;   // "Acme"
getSet();      // snapshot the active identity - JSON-safe, version it in your repo
```

--------------------------------

### getSet()

Source: https://usefoley.dev/docs.html

Retrieves the current active sound identity as a JSON-safe object.

```APIDOC
## getSet()

### Description
Returns the active sonic identity as a portable JSON object, which can be used for versioning or re-applying the state later.
```

--------------------------------

### play(cue)

Source: https://usefoley.dev

Triggers a programmatic sound cue for events not initiated by a direct user click.

```APIDOC
## play(cue)

### Description
Plays a specific sound cue programmatically. Useful for system notifications or events that do not originate from a direct user interaction.

### Parameters
- **cue** (string) - Required - The identifier of the sound to play. Supported values: "ping", "chime", "error", "rise", "complete".

### Example
play("ping");
```

--------------------------------

### Designing and Playing Custom Cues

Source: https://usefoley.dev/docs.html

Retrieve a sound specification, modify its layers, and play or export the result. Requires importing core functions from @foleyjs/core.

```javascript
import { getSpec, playSpec, toWavSpec } from "@foleyjs/core";

const mySound = getSpec("success");
mySound[2].f = 880;                  // raise the last note
mySound.push({ kind: "noise", at: 0.2, filter: "highpass", f: 6000,
               a: 0.01, d: 0.2, peak: 0.05, send: 0.4 });
playSpec(mySound);
const wav = await toWavSpec(mySound);
```

--------------------------------

### Markup and Bind FoleyJS

Source: https://usefoley.dev

Apply data attributes to HTML elements for declarative behavior and initialize the library to wire them up.

```html
<!-- one attribute per behavior -->
<button data-foley-press data-foley-release>Save</button>
<a data-foley-hover="tick">Docs</a>
<button data-foley-toggle>Dark mode</button>
<input data-foley-type="thock">
```

```javascript
import { bind, play, set } from "@foleyjs/core";

bind();                     // wires every data-foley-*
set({ volume: 0.7,          // 0 – 1
      transpose: 0,         // semitones, ±12
      space: 0.2,           // reverb send
      theme: "glass" });    // a name — or your sound set object

play("complete");           // any of the 28 cues
set({ theme: brandSet });   // load your identity — build one in the designer ↓
play("tick", { pitch: 4, volume: 0.3 });

const wav = await toWav("chime"); // Blob — offline render
```

--------------------------------

### toWav(name)

Source: https://usefoley.dev/docs.html

Offline-renders a cue to a 16-bit 44.1 kHz stereo WAV file.

```APIDOC
## toWav(name)

### Description
Returns a `Promise<Blob>` containing the rendered WAV file for the specified cue name, honoring current global settings.
```

--------------------------------

### Toggle interaction

Source: https://usefoley.dev

Provides distinct sounds for on and off states.

```html
data-foley-toggle
```

--------------------------------

### Initialize Foley in Vue 3

Source: https://usefoley.dev/docs.html

Register the Foley plugin and apply the v-foley directive to elements.

```javascript
app.use(FoleyPlugin)
```

```html
<button v-foley="'success'">
```

--------------------------------

### Programmatic notifications

Source: https://usefoley.dev

Triggers specific sound cues for system events.

```javascript
play("ping" | "chime" | "error")
```

--------------------------------

### Two-part press interaction

Source: https://usefoley.dev

Uses separate attributes for press and release actions to simulate mechanical feedback.

```html
data-foley-press · data-foley-release
```

--------------------------------

### Stepper interaction

Source: https://usefoley.dev

Uses a tick sound with dynamic pitch based on the count.

```html
data-foley-click="tick" + pitch
```

--------------------------------

### Typing feedback

Source: https://usefoley.dev

Plays a mechanical sound per keystroke with a flourish on Enter.

```html
data-foley-type="thock"
```

--------------------------------

### Integrate FoleyJS with React and Vue

Source: https://usefoley.dev

Use framework-specific packages to integrate FoleyJS into React components or Vue templates.

```javascript
// npm install @foleyjs/react
import { useFoley } from "@foleyjs/react";

function App() {
  const { play } = useFoley({ volume: 0.7 });
  return <button onClick={() => play("success")}>
    Save
  </button>;
}
```

```javascript
// npm install @foleyjs/vue
import { FoleyPlugin } from "@foleyjs/vue";
app.use(FoleyPlugin, { theme: "soft" });

<!-- then in any template -->
<button v-foley="'success'">Save</button>
<a v-foley:hover="'tick'">Docs</a>
```

--------------------------------

### Hover ticks

Source: https://usefoley.dev

Triggers a subtle sound when the pointer crosses an element.

```html
data-foley-hover="tick"
```

--------------------------------

### Slider interaction

Source: https://usefoley.dev

Plays detent ticks that adjust pitch based on the slider value.

```javascript
play("tick", { pitch })
```
Tokens:
Raw