deepset-ai--haystack/docs-website/docs/concepts/components/custom-components.mdx

---
title: "Creating Custom Components"
id: custom-components
slug: "/custom-components"
description: "Create your own components and use them standalone or in pipelines."
---

# Creating Custom Components

Create your own components and use them standalone or in pipelines.

With Haystack, you can easily create any custom components for various tasks, from filtering results to integrating with external software. You can then insert, reuse, and share these components within Haystack or even with an external audience by packaging them and submitting them to [Haystack Integrations](../integrations.mdx)!

## Requirements

Here are the requirements for all custom components:

- `@component`: This decorator marks a class as a component, allowing it to be used in a pipeline.
- `run()`: This is a required method in every component. It accepts input arguments and returns a `dict`. The inputs can either come from the pipeline when it’s executed, or from the output of another component when connected using `connect()`. The `run()` method should be compatible with the input/output definitions declared for the component. See an [Extended Example](#extended-example) below to check how it works.


:::note[Avoid in-place input mutation]

When building custom components, do not change the component's inputs directly. Instead, work on a copy or a new version of the input, modify that, and return it. The reason for this is that the original input values might be reused by other components or by later pipeline steps. Mutating the input directly can lead to unintended side effects and bugs in the pipeline, as other components might rely on the original input values.

When only one or a few fields of the input need to be changed (for example, `meta` on a `Document`), use `dataclasses.replace()` to create a new instance with the updated fields. This is simpler and more efficient than deep-copying the whole object:

```python
from dataclasses import replace


def run(self, documents):
    updated = [replace(doc, meta={**doc.meta, "processed": True}) for doc in documents]
    return {"documents": updated}
```

When you need to modify nested mutable structures, for example `list` or `dict` attributes, or update many fields of the dataclass instance, use a full deep copy instead:

```python
import copy


def run(self, documents):
    documents_copy = copy.deepcopy(documents)
    # mutate documents_copy safely here
    return {"documents": documents_copy}
```

:::


### Inputs and Outputs

Next, define the inputs and outputs for your component.

#### Inputs

You can choose between three input options:

- `set_input_type`: This method defines or updates a single input socket for a component instance. It’s ideal for adding or modifying a specific input at runtime without affecting others. Use this when you need to dynamically set or modify a single input based on specific conditions.
- `set_input_types`: This method allows you to define multiple input sockets at once, replacing any existing inputs. It’s useful when you know all the inputs the component will need and want to configure them in bulk. Use this when you want to define multiple inputs during initialization.
- Declaring arguments directly in the `run()` method. Use this method when the component’s inputs are static and known at the time of class definition.

#### Outputs

You can choose between two output options:

- `@component.output_types`: This decorator defines the output types and names at the time of class definition. The output names and types must match the `dict` returned by the `run()` method. Use this when the output types are static and known in advance. This decorator is cleaner and more readable for static components.
- `set_output_types`: This method defines or updates multiple output sockets for a component instance at runtime. It’s useful when you need flexibility in configuring outputs dynamically. Use this when the output types need to be set at runtime for greater flexibility.

## Short Example

Here is an example of a simple minimal component setup:

```python
from haystack import component


@component
class WelcomeTextGenerator:
    """
    A component generating personal welcome message and making it upper case
    """

    @component.output_types(welcome_text=str, note=str)
    def run(self, name: str):
        return {
            "welcome_text": f"Hello {name}, welcome to Haystack!".upper(),
            "note": "welcome message is ready",
        }
```

Here, the custom component `WelcomeTextGenerator` accepts one input: `name` string and returns two outputs: `welcome_text` and `note`.

## Extended Example

Check out an example below on how to create two custom components and connect them in a Haystack pipeline.

```python
# import necessary dependencies
from haystack import component, Pipeline


# Create two custom components. Note the mandatory @component decorator and @component.output_types, as well as the mandatory run method.
@component
class WelcomeTextGenerator:
    """
    A component generating personal welcome message and making it upper case
    """

    @component.output_types(welcome_text=str, note=str)
    def run(self, name: str):
        return {
            "welcome_text": (
                "Hello {name}, welcome to Haystack!".format(name=name)
            ).upper(),
            "note": "welcome message is ready",
        }


@component
class WhitespaceSplitter:
    """
    A component for splitting the text by whitespace
    """

    @component.output_types(split_text=list[str])
    def run(self, text: str):
        return {"split_text": text.split()}


# create a pipeline and add the custom components to it
text_pipeline = Pipeline()
text_pipeline.add_component(
    name="welcome_text_generator",
    instance=WelcomeTextGenerator(),
)
text_pipeline.add_component(name="splitter", instance=WhitespaceSplitter())

# connect the components
text_pipeline.connect(
    sender="welcome_text_generator.welcome_text",
    receiver="splitter.text",
)

# define the result and run the pipeline
result = text_pipeline.run({"welcome_text_generator": {"name": "Bilge"}})

print(result["splitter"]["split_text"])
```

## Extending the Existing Components

To extend already existing components in Haystack, subclass an existing component and use the `@component` decorator to mark it. Override or extend the `run()` method to process inputs and outputs. Call `super()` with the derived class name from the init of the derived class to avoid initialization issues:

```python
class DerivedComponent(BaseComponent):
    def __init__(self):
        super(DerivedComponent, self).__init__()


# ...

dc = DerivedComponent()  # ok
```

An example of an extended component is Haystack's [FaithfulnessEvaluator](https://github.com/deepset-ai/haystack/blob/e5a80722c22c59eb99416bf0cd712f6de7cd581a/haystack/components/evaluators/faithfulness.py) derived from LLMEvaluator.

## Project Template

If you're building a custom component that you want to package and share, we provide a [GitHub template repository](https://github.com/deepset-ai/custom-component) that gives you a ready-made project structure. It includes the boilerplate for packaging, testing, and distributing your custom component as a standalone Python package. Use it to quickly scaffold a new integration or reusable component without setting up the project from scratch.

Check out the [video walkthrough](https://www.youtube.com/watch?v=SWC0QecAMcI) for a step-by-step guide on how to use the template.

## Additional References

🧑‍🍳 Cookbooks:

- [Build quizzes and adventures with Character Codex and llamafile](https://haystack.deepset.ai/cookbook/charactercodex_llamafile/)
- [Run tasks concurrently within a custom component](https://haystack.deepset.ai/cookbook/concurrent_tasks/)
- [Chat With Your SQL Database](https://haystack.deepset.ai/cookbook/chat_with_sql_3_ways/)
- [Hacker News Summaries with Custom Components](https://haystack.deepset.ai/cookbook/hackernews-custom-component-rag/)