# Custom Components
### Overview
When you've spent time configuring and styling a set of components — a slider with a label, a button with a status indicator, a polished input form — Custom Components let you save that combination as a single reusable item. Place it in any project, and if you ever need to update it, all instances across your apps can pick up the change.
This saves you from rebuilding the same thing repeatedly and keeps your apps consistent.
{% hint style="info" %}
Custom Component instances are identifiable on the canvas by a **purple border**, compared to the standard blue border used on regular components. They also carry a distinctive icon in the component tree.
{% endhint %}
***
### Creating a Custom Component
{% hint style="warning" %}
You cannot create a Custom Component if the selection contains a Canvas, an existing Custom Component, a Repeat Container, a Data Grid, a Scenario, or a grid area component.
{% endhint %}
Select one or more components on the canvas, then convert them into a Custom Component using any of the following methods:
* Right-click selected components in the **component tree** and choose **Create Custom Component**
* Right-click selected components on the **canvas** and choose **Create Custom Component**
* With eligible components selected, click the **cube icon** in the top-right corner of the properties panel header — the icon highlights purple on hover and displays the tooltip **Create Component**
All three methods open a **name modal**. Enter a name for your component and click **Continue** to proceed, or **Cancel** to return to the canvas without creating anything.
Once named, the original components are replaced by a Custom Component instance and the designer automatically enters **Edit Mode**.
{% hint style="info" %}
When you create a Custom Component any bindings will be automatically removed when you enter the edit mode. Instead you will have to create "Linked Properties" as described [below](#linked-properties).
{% endhint %}
***
### Edit Mode
Edit Mode is a dedicated workspace for modifying a Custom Component's internal layout and defining its configurable interface. The normal designer menu bar is replaced by a **purple header bar** containing Edit Mode controls.
**EDIT MODE HEADER**
**Back arrow** — exits Edit Mode and returns to the main project. If unsaved changes exist, you are prompted with a dialog offering **Discard and Exit** or **Update Component** before leaving.
**Component name** — the name of the Custom Component is displayed inside the purple header. Double-click the name to rename it inline.
**Update button** — saves the current state of the component to the cloud, and closes Edit Mode. The button is active only when unsaved changes exist.
**ENTERING EDIT MODE**
Beyond the creation flow, Edit Mode can be entered at any time by right-clicking an instance in the **component tree** and selecting **Edit Custom Component**, by right-clicking an instance on the **canvas** and selecting **Edit Custom Component**, or by navigating to the new **Asset Library > Components** page in the Squirrel manager.
{% hint style="info" %}
If the selected instance is on an older version of the component, you will be prompted to update it before Edit Mode opens.
{% endhint %}
**EDITING INTERNAL COMPONENTS**
While in Edit Mode the canvas displays only the custom component's contents. Add, remove, and configure components exactly as you would on a normal canvas. The spreadsheet panel is not available in Edit Mode.
***
### Linked Properties
Linked Properties are the configurable interface of a Custom Component. They are named properties defined on the **Component Canvas** that instances can bind spreadsheet data to. Define Linked Properties in the properties panel while in Edit Mode.
**CREATING PROPERTIES**
Select **Add a property** in the Linked Properties section of the properties panel. An input field appears — enter a descriptive name for the property, such as `Title` or `Primary Colour`. Each property is assigned a unique identifier internally, so renaming a property later does not break any existing bindings. Repeat to add as many properties as the component requires.
{% hint style="warning" %}
Deleting a linked property, which has been used in a component, will stop the binding from working
{% endhint %}
The **Links** number column indicates how many times this linked property has been used. Clicking on the number will display a list of the components where the property has been bound.
**LINKING TO COMPONENTS**
1. With a Linked Property defined, select a component in the component tree to view its individual properties.
2. Hover over any bindable property input — the bind button turns purple to indicate it can be connected to a Linked Property.
3. Click the purple bind button to open a list of available Linked Properties.
4. Select a property from the list to create the link.
When all links are configured, click the purple Update button to save the changes and exit Edit Mode.
{% hint style="info" %}
A single Linked Property can be connected to multiple internal component properties at once. For example, a `Primary Colour` property can simultaneously control the fill colour of a button and the text colour of a label.
{% endhint %}
***
### Custom Component Properties
The following properties are available in the properties panel when a Custom Component instance is selected on the canvas.
**LAYOUT & POSITIONING**
**Position** and **Size** — standard X, Y, Width, and Height controls for placing and sizing the instance on the canvas.
**LINKED PROPERTIES**
Lists every Linked Property defined in the custom component. Each property has an input field where you can bind a spreadsheet cell or range — data flows from that range through to the connected internal components.
**CREATE PROPERTIES**
The **Create properties** button enters Edit Mode for this custom component directly from the properties panel. Any changes made in Edit Mode affect all instances of the item across every project.
**DYNAMIC VISIBILITY**
Standard conditional show/hide controls for displaying or hiding the instance based on data conditions.
***
### Placing Custom Components
Saved Custom Components are available from the **Custom Components** section of the side bar. Click the section to browse all custom components saved to your account.
Single-click a custom component to add an instance to the canvas, or drag it directly to a specific position. Each instance placed is independent and can be positioned, sized, and configured with different spreadsheet bindings.
{% hint style="info" %}
The Custom Components library is **personal to your account** in the current release. Shared team libraries are planned for a future update.
{% endhint %}
***
### Updating Custom Components
When a Custom Component is edited and saved, a new version is created. Any instances in the currenlty open file will wil be updated to the latest version.
{% hint style="info" %}
Updates to other Squirrel files that use the Custom Component are not applied automatically. You will be notified when opening a file if any Custom Components have updates available, and can choose when to apply them.
{% endhint %}
**UPDATE INDICATORS**
A **purple dot** indicator appears on the properties panel of any instance where a newer version of the custom component is available. Right-clicking the instance also reveals a **View all Component Updates** option, which opens the master update modal listing every out-of-date component in the current project.
**UPDATING INSTANCES**
**Update Component** — available in the right-click menu on a selected instance. Updates the selected instance to the latest version, or optionally all instances of that custom component in the project.
**Update all components** — available in the master update modal. Updates every out-of-date Custom Component in the current project at once.
***
### Detaching an Instance
Detaching breaks the link between an instance and its source component, converting it back into an editable container of independent components.
Right-click an instance on the canvas or in the component tree and select **Detach Instance**. The instance is converted to a **container** that holds all of the original internal components. The components retain their names and positions, and the container keeps them grouped for easy layout management. However, all linked property bindings are removed.
{% hint style="warning" %}
Detaching cannot be undone. The source component is not affected, and all other instances of that custom component remain linked.
{% endhint %}
***
### Managing Custom Components
Custom Components are saved to your Asset Library. These can be browsed and managed from **Asset Library → Components** in the Squirrel home page.
Clicking the **more menu** **`...`** provides access the following options.
* **Rename** — updates the display name of the custom component. The name change is reflected across the library and in the properties panel of all instances.
* **Edit Component** — opens the custom component in Edit Mode in a clean workspace, without needing to open a project that uses it first.
* **Delete** — removes the custom component from the asset library.
{% hint style="warning" %}
Deleting a custom component **does not** remove existing instances from projects. Those instances remain on their respective canvases but are no longer linked to a source component and cannot receive future updates.
{% endhint %}
