Reusable Components are the foundation of modular, scalable design in Shipcode. They allow you to build sophisticated UI elements once and then share and update them instantly across your entire project. By using Reusable Components, you ensure visual consistency and speed up iteration—especially in large or complex applications.

Overview and Concepts

• When to Use Them: As a general guide, you should create a reusable component if you find yourself using the same element (or design pattern) more than three times throughout your application's experience.
• Main Component: When you create a reusable component, the master version is saved to your project's component library, which is organized by Storyboards. This master version is the single source of truth for all instances.
• Component Instance: When you reuse a component on a Layout, it is called a component instance. You can quickly identify an instance by its distinct purple color in the Structure Panel and its open diamond icon.
• Propagation: Component instances are exact copies of the main component. If you make a change to the main component (e.g., updating a color or padding), that change automatically propagates to all instances.

Managing Component Overrides

Overrides are specific changes made to a property on an instance that diverge from the main component's properties. If a property on an instance has been overridden (e.g., you changed the background color of a button instance), future changes to that specific property on the main component will not affect the overridden instance.

Make an Override on a Component Instance

1. Select a component instance on any Layout.
2. Change any property in the Right Sidebar (e.g., in the Appearance Panel).
3. Observe that a blue dot is now present next to the property's label, indicating a local override has been created.
4. Click the blue dot to see a context menu that displays all overrides currently applied to that component instance.

Remove an Override or Reset to Default

• To remove a single override: Select the component instance, click the blue dot next to the prop label in the Right Sidebar, and then use the trash can icon within the context menu.
• To remove all overrides:
• 1. Navigate to the component instance editor at the top of the Appearance Panel.
  2. Click the three-dot menu and select Reset All Changes. This instantly restores the instance to the exact state of the main component.

Working with Reusable Components

Create a Reusable Component

1. Design your component (or group of components) on a Layout.
2. Select the parent layer of the component you want to save.
3. Right-click on the canvas or in the Structure Panel and select Create Component.
4. A modal will appear where you can add a name for the component and assign it to a Storyboard.

Reusing Your Component (Component Instances)

You can place component instances onto your Layouts using two primary methods:

• Components Panel:
• 1. Open the Components Panel in the Layout Editor.
  2. Select the Components tab.
  3. Your reusable components will be organized by Storyboard. Drag and drop the selected component onto your Layout.
• Command Palette (Shortcut):
• 1. Open the Command Palette (Cmd + Shift + P or Ctrl + Shift + P).
  2. Type the component's name and click to add it to your Layout.
• Library Note: For reusable components from an external Library, go to the Libraries tab in the Components Panel.

Navigate to a Main Component

To edit the master source of truth, you can navigate directly from any instance:

• Layout Editor Link: Select a component instance on a Layout, then navigate to the top of the Appearance Panel. In the component instance editor, click the link for Edit Main.

• Top Bar Navigation: Click the Components tab in the Top Bar, select the Storyboard where the main component was saved, and select the component from the Structure Panel.

Swap a Component Instance

You can quickly swap one instance for a different Reusable Component:

1. Select a component instance on your Layout.
2. Navigate to the component instance editor at the top of the Appearance Panel.
3. Click the component dropdown to open the menu.
4. Select the new Reusable Component you want to use.

📍📍📍 Note 📍📍📍

Nested component instances cannot be swapped directly in the Layout Editor. If you need to swap an inner component, you must make that change within the structure of the main component itself.

Detach a Component Instance

Detaching is the action that breaks the link between the instance and the main component. The instance then becomes an independent group of components that will no longer receive updates.

1. Select the component instance in the Layout Editor.
2. Choose one of the following methods:
3. • Use the three-dot menu in the Appearance Panel and select Detach Instance.
   • Right-click on the canvas and select Detach Instance.
   • Right-click on the selected layer in the Structure Panel and select Detach Instance.

Delete a Main Component vs. Instance

• Component Instance: Deleting the instance removes only the instance from the Layout. The main component remains in the component library.
• Main Component: Deleting the main component removes it from the Storyboard. If an instance of a deleted main component still exists on a Layout, you can restore the main component by:
• 1. Going to the Appearance Panel of the orphaned instance.
  2. Clicking Restore Main Component to re-add it to the Storyboard.