---
url: https://docs.fluxify.rest/blocks/custom-blocks.md
description: >-
  Build your own reusable block from other blocks, and use it in any route or
  workflow in your project.
---

# Custom Blocks

A **custom block** is a block you build yourself. You wire a few existing blocks together once, give the result a name and an icon, and from then on it shows up in the block picker like any built-in block.

Use one when you catch yourself copying the same group of blocks from route to route: sending the same Slack message, checking the same token, calling the same internal API. Build it once, and fix it in one place.

> Want to build one now? Follow the [step-by-step tutorial](./custom-blocks-tutorial.md).

## How it works

A custom block has two sides.

**The inside** is a canvas, just like a route's canvas. It starts at an **Entrypoint**, runs through whatever blocks you add, and whatever the last block produces is what the custom block gives back.

**The outside** is a small settings form that you design. These are the block's **input parameters**. Whoever places your block on a canvas fills them in, the same way they fill in an HTTP Request block's URL and method.

```mermaid
flowchart LR
    A["Previous block"] -->|input| B["Your custom block"]
    S["Settings filled in on the canvas"] -->|params| B
    B -->|output| C["Next block"]
```

Inside the custom block you can read two things:

| Name | What it is |
| :--- | :--- |
| `input` | The output of the block that came before your custom block. |
| `params` | The settings filled in on the block, for example `params.webhook_url`. |

Both work anywhere a field accepts JavaScript (a `js:` expression, or the JS Runner block).

## Input parameters

Each parameter becomes a field on the block's **Parameters** tab. Pick the kind of field that fits:

| Kind | What the user sees | Good for |
| :--- | :--- | :--- |
| **Text input** | A text box that accepts a `js:` expression | URLs, names, messages |
| **Checkbox** | A tick box | On/off options |
| **Dropdown** | A list of choices you define | A fixed set of options |
| **Array editor** | A list the user can add items to | Lists of values |
| **Integration selector** | A picker for one of the project's [integrations](../integrations/index.md) | Choosing which database or queue to use |
| **App Config selector** | A picker for an [App Config](../concepts/app-config.md) key | Secrets and API keys |

Every parameter has an **identifier** (lowercase letters, numbers and underscores, such as `webhook_url`), a **label** shown to the user, and an optional hint.

> For secrets, prefer the **App Config selector** over a text input. The user picks the *name* of the secret, so the secret itself never gets written into the canvas. Read it inside the block with `getConfig(params.your_identifier)`.

## Using a custom block

Open the block picker on any route or workflow canvas. Your custom blocks are listed there with their icon and description. Drop one on the canvas, connect it, and fill in its **Parameters** tab.

The **General** tab has an **Execution Mode**:

| Mode | What happens |
| :--- | :--- |
| **Synchronous** (default) | The flow waits for the custom block and uses its output. If it fails, the flow fails too. |
| **Asynchronous** | The custom block starts and the flow carries on straight away. Its output is not available. If the server restarts while it is running, the work is lost. |
| **Queued** | The work is saved as a background job and run later. It survives a restart and may be retried, so make it safe to run twice. Only the block's parameters and input are handed over, so request details such as headers, cookies and variables are not available inside it. |

Like other blocks that produce data, a custom block can **save its output to a variable** so later blocks can read it.

## Turning blocks you already have into a custom block

Built a flow that works in a sandbox or a route and want to reuse it? Select its blocks on the canvas, right-click and choose **Extract to custom block…**. Give it a label (the name fills in for you) and Fluxify creates the custom block with those blocks and the connections between them. Tick **Replace the selection with the new block** to swap the selected blocks for one copy of the new block on the canvas you started from.

The custom block gets the default icon and no input parameters: it receives the output of the block before it as `input`, and returns whatever its last block returns. Open it afterwards to add a description, an icon or input parameters. Unsaved changes on the canvas are saved first.

The selection has to be tidy so the new block is not a tangle:

* One entry block, with at most one connection coming in from outside the selection.
* At most one connection going out, from the selection's last block.
* No connections from outside into, or out of, the middle of the selection.

If it is not, nothing is created and the message says what to clean up. If the selection ends in several blocks, the new block has no single output; connect them the way you want afterwards.

The new block is available straight away on development. Like any custom block, it needs a promoted version before a route that uses it can go to production.

## Plugin blocks

Blocks written in code and shared as a package are called [plugins](/plugins/). To see them next to your custom blocks, tick **Show plugin blocks** at the top of the **Custom Blocks** page. They are read-only here; manage them under **Settings → Plugins**.

## Good to know

* Custom blocks belong to a project. They are available to every route and workflow in that project, and not to other projects.
* When you change a custom block, every route that uses it picks up the change.
* Give the block a clear label and description. Those are what your teammates see in the block picker.
* Keep a block focused on one job. A block that does one thing is easy to reuse.
* You can reopen a custom block's canvas from the **Custom Blocks** page, or from a placed block by pressing **Edit Implementation** on its **General** tab.

## Where a custom block can be used

When you create a custom block, **Used for** decides where it can run. You pick
it once: it can't be changed later, because routes, test suites and middlewares
depend on it.

| Used for | Where it runs |
| --- | --- |
| **Routes & workflows** (default) | On any route, workflow or custom block canvas, from the block picker. |
| **Test setup & teardown** | Only before or after a [test suite](/testing/). Hidden from the block picker. See [Setup and Teardown](/testing/setup-and-teardown). |
| **Middleware** | Only as a step of a [middleware](/concepts/middlewares), before or after a route. Takes no input parameters and is hidden from the block picker. |
