# How to Create ComfyUI Nodes with SEARCH_ALIASES for Better Discoverability

> Learn to make ComfyUI nodes more discoverable using SEARCH_ALIASES. Improve your workflow by easily finding custom nodes with alternative search terms in the palette.

- Repository: [Comfy Org/ComfyUI](https://github.com/Comfy-Org/ComfyUI)
- Tags: how-to-guide
- Published: 2026-02-26

---

**Add a `SEARCH_ALIASES` class attribute to legacy nodes or pass `search_aliases` to `io.Schema` in modern nodes to make them searchable by alternative names in the ComfyUI node palette.**

Finding the right node in a crowded ComfyUI workflow can be frustrating for users. The Comfy-Org/ComfyUI repository provides a `SEARCH_ALIASES` mechanism that allows node developers to expose alternative searchable terms, ensuring users can locate specific functionality through the web interface search bar and the `/object_info` API endpoint.

## Two Methods to Define SEARCH_ALIASES

ComfyUI supports two distinct patterns for defining search aliases depending on which node base class you inherit from. Both methods ultimately populate the same index consumed by the frontend.

### Legacy Class Attribute Approach

For nodes inheriting from `ComfyNodeABC` (the classic base class), define a class-level list named `SEARCH_ALIASES`. The server extracts this attribute in [`server.py`](https://github.com/Comfy-Org/ComfyUI/blob/main/server.py) at line 691:

```python

# server.py – line 691

info['search_aliases'] = getattr(obj_class, 'SEARCH_ALIASES', [])

```

Many built-in nodes in [`nodes.py`](https://github.com/Comfy-Org/ComfyUI/blob/main/nodes.py) (lines 74-159) use this pattern. For example, `CLIPTextEncode` and `ConditioningCombine` expose aliases that help users find these nodes when searching for related concepts.

### Modern Schema-Based Approach

For nodes using the newer `io.ComfyNode` base class, pass the `search_aliases` parameter when constructing the `io.Schema`. This approach is demonstrated in [`comfy_extras/nodes_string.py`](https://github.com/Comfy-Org/ComfyUI/blob/main/comfy_extras/nodes_string.py) at line 14:

```python

# comfy_extras/nodes_string.py – line 14

search_aliases=["text concat", "join text", …]

```

The server automatically checks for this field in the schema definition if the legacy attribute is not present, ensuring backward compatibility while supporting modern node architecture.

## Step-by-Step Implementation

Follow these steps to add discoverable aliases to your custom node:

1. **Create your node file** in the `custom_nodes/` directory (e.g., [`my_custom_node.py`](https://github.com/Comfy-Org/ComfyUI/blob/main/my_custom_node.py)).

2. **Choose your inheritance pattern**:
   - **Legacy**: Subclass `ComfyNodeABC` from `comfy.comfy_types`
   - **Modern**: Subclass `io.ComfyNode` from `comfy_api.latest`

3. **Implement the aliases**:
   - **For legacy nodes**, add the class attribute:
     ```python
     class MyLegacyNode(ComfyNodeABC):
         SEARCH_ALIASES = ["demo", "legacy test", "quick add"]
         
         @classmethod
         def INPUT_TYPES(s) -> InputTypeDict:
             return {
                 "required": {
                     "value": (IO.INT, {"default": 1, "min": 0, "max": 100}),
                 }
             }
         
         RETURN_TYPES = (IO.INT,)
         FUNCTION = "process"
         CATEGORY = "utils/custom"
         
         def process(self, value):
             return (value + 10,)
     ```

   - **For modern nodes**, define within the schema:
     ```python
     from comfy_api.latest import io

     class MyModernNode(io.ComfyNode):
         @classmethod
         def define_schema(cls):
             return io.Schema(
                 node_id="MyModernNode",
                 display_name="My Modern Node",
                 category="utils/custom",
                 search_aliases=["demo", "modern test", "quick compute"],
                 inputs=[
                     io.Float.Input("factor", default=1.0),
                     io.Int.Input("offset", default=0),
                 ],
                 outputs=[
                     io.Float.Output(display_name="result"),
                 ]
             )

         @classmethod
         def execute(cls, factor, offset):
             return io.NodeOutput(factor * 2 + offset)
     ```

4. **Reload the UI** or restart ComfyUI. The aliases immediately become searchable in the node palette.

## Verifying Aliases via the API

Confirm your implementation by querying the `/object_info` endpoint. The server includes the alias list in the JSON payload for each node:

```bash
curl http://localhost:8188/object_info | jq '.["MyModernNode"].search_aliases'

```

Expected output:

```json
[
  "demo",
  "modern test",
  "quick compute"
]

```

This JSON structure feeds directly into the global search index, enabling both the web UI and external tools to surface your node when users type any of the specified aliases.

## Summary

- **SEARCH_ALIASES** improves node discoverability by mapping alternative search terms to your node class.
- **Legacy nodes** use a class attribute (`SEARCH_ALIASES = ["term1", "term2"]`) extracted by [`server.py`](https://github.com/Comfy-Org/ComfyUI/blob/main/server.py).
- **Modern nodes** use the `search_aliases` parameter in `io.Schema` as shown in [`comfy_extras/nodes_string.py`](https://github.com/Comfy-Org/ComfyUI/blob/main/comfy_extras/nodes_string.py).
- The **Web UI** performs case-insensitive, partial matching against these aliases.
- The **`/object_info`** endpoint exposes aliases to external tools and extensions.

## Frequently Asked Questions

### What is the maximum number of aliases I should define?

Define **3 to 5 concise, distinct terms** that cover common synonyms or related concepts. Avoid excessive aliases that dilute search precision. The ComfyUI frontend indexes all provided strings, but cluttered results can overwhelm users.

### Can I use SEARCH_ALIASES with any custom node class?

Yes, provided your node is properly registered in the ComfyUI node system. The server in [`server.py`](https://github.com/Comfy-Org/ComfyUI/blob/main/server.py) uses `getattr(obj_class, 'SEARCH_ALIASES', [])`, which safely returns an empty list if the attribute is missing. For modern nodes using `io.ComfyNode`, ensure you import `comfy_api.latest` and define a valid `io.Schema`.

### Do search aliases affect node execution or only the UI?

Aliases affect **only discoverability**, not execution logic. They are metadata consumed by the frontend and the `/object_info` API endpoint. The actual computation in your `FUNCTION` (legacy) or `execute` (modern) method remains unchanged regardless of which alias a user searched to find the node.

### How do I debug if my aliases are not appearing?

First, verify your node loads without errors in the ComfyUI console. Then query the `/object_info` endpoint and check the `search_aliases` field for your specific `node_id`. If the field is empty or missing, confirm you used the correct attribute name (`SEARCH_ALIASES` for legacy, `search_aliases` for schema-based) and that your class inherits from the appropriate base (`ComfyNodeABC` or `io.ComfyNode`).