> For the complete documentation index, see [llms.txt](https://docs.protoboard.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.protoboard.xyz/user-guide/parts-add-edit-custom.md).

# Parts: Add / Edit / Custom

Search the parts library, edit part properties, create blank custom parts, and manage part templates.

## Goal

Find the right parts for your design, customize them when needed, and understand how part templates keep everything in sync.

***

## Adding parts from the library

{% stepper %}
{% step %}

#### Open the Parts Bin

Click the **cuboid icon** in the left sidebar. The Parts Bin slides open, showing available parts as visual cards with domain badges.
{% endstep %}

{% step %}

#### Search for a part

Type a name, keyword, or description into the search bar. Protoboard uses **AI-powered semantic search** with keyword fallback, so natural queries like "3.3V voltage regulator" or "I2C accelerometer" return relevant results.

Can't find what you need? Use the **Request Part** button in the Parts Bin to submit a request. The ProtoPart library is growing continuously.
{% endstep %}

{% step %}

#### Filter by domain

Narrow results by selecting a domain filter:

* **Electrical**
* **Mechanical**
* **Pneumatic**
* **Hydraulic**
* **Network**
  {% endstep %}

{% step %}

#### Place the part

Drag a part card from the library onto the canvas. An orange preview follows your cursor. Release to place.
{% endstep %}
{% endstepper %}

***

## Part properties

Every part has a set of properties that define what it is and how it connects to other parts:

{% columns %}
{% column %}

#### Identity

* **Name**: display name on the canvas
* **Categories**: classification tags
* **Description**: what the part does
* **Manufacturer**: who makes it
* **Part number**: manufacturer reference
* **Datasheet URL**: link to the official datasheet
  {% endcolumn %}

{% column %}

#### Technical

* **Domains**: which system domains the part belongs to (Electrical, Mechanical, etc.)
* **Resources**: the internal capabilities the part offers (GPIO pins, power rails, communication peripherals, etc.)
* **Interfaces**: the external connection points other parts can link to (I2C bus, UART port, power input, etc.)
  {% endcolumn %}
  {% endcolumns %}

***

## Editing a part

Select any part on the canvas and open the **Inspector** panel to view and edit its properties. You can modify the part name, description, and all technical fields.

{% hint style="info" %}
Edits apply to the part's **template** within your project. Other boards using the same template are not affected unless you explicitly push changes.
{% endhint %}

***

## Part templates

Parts in Protoboard are managed through **templates**. When you add a part from the library, a project-local copy of its template is created. This system lets you customize parts without affecting the shared library.

### Template sync status

| Status         | Meaning                                                              |
| -------------- | -------------------------------------------------------------------- |
| **Synced**     | Your local template matches the library version                      |
| **Ahead**      | You have made local edits not yet in the library                     |
| **Local-only** | This template exists only in your project (e.g., blank parts)        |
| **Broken**     | The template reference is invalid or the library version was removed |

### Template actions

* **Edit JSON**: directly edit the template definition for advanced users
* **Pull latest**: update your local template to match the current library version
* **Clone**: create a duplicate template for experimentation
* **Delete**: remove the template from your project
* **Import**: bring in a template from a file or another source

***

## Creating blank (custom) parts

When the library does not have what you need, create a **blank part** from scratch.

{% stepper %}
{% step %}

#### Start a blank part

In the Parts Bin, select the option to create a **Blank Part**. A new empty part is added to your canvas.
{% endstep %}

{% step %}

#### Set the minimum required fields

Every part needs at least:

1. **Identifier**: a unique name
2. **At least one domain**: such as Electrical or Mechanical
3. **Resources**: the internal functions the part provides
4. **Interfaces**: the connection points other parts can use

{% hint style="warning" %}
If any of these four fields are missing, the part will not pass validation and cannot be connected properly.
{% endhint %}
{% endstep %}

{% step %}

#### Fill in additional details

Add a description, manufacturer info, datasheet link, and any other properties to make the part useful for your team and for BOM generation.
{% endstep %}
{% endstepper %}

***

## Common failures

<details>

<summary>My custom part does not appear as connectable</summary>

Make sure you have defined at least one **interface** with a valid protocol type and role. Parts without interfaces have no connection points for harnesses.

</details>

<details>

<summary>Search is not returning the part I expect</summary>

Try different keywords or a more descriptive phrase. The AI search understands intent, so "motor controller for DC brushed" may work better than a specific part number. You can also filter by domain to narrow results.

</details>

<details>

<summary>My part template shows "Broken" status</summary>

This means the library version the template references no longer exists. You can continue using your local copy, or delete the template and re-add the part from the library.

</details>

<details>

<summary>I edited a part but the changes are not showing on the canvas</summary>

Ensure you saved your edits in the Inspector. If you edited the JSON directly, check for syntax errors that might prevent the changes from being applied.

</details>

***

## Related pages

* [Canvas Basics](/user-guide/canvas-basics.md): place and arrange parts on the canvas
* [Connections & Compatibility](/user-guide/connections-and-compatibility.md): connect parts and check compatibility
* [Validation (DRC)](/user-guide/validation-drc.md): verify that parts are properly configured
* [BOM + Export](/user-guide/bom-and-export.md): see your parts in the bill of materials


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.protoboard.xyz/user-guide/parts-add-edit-custom.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.