# Components

## Overview

**Components** are the building blocks of reusability in Digia. A Component is a custom widget you create once and use everywhere. By bundling multiple widgets and logic into a single unit, you ensure consistency and drastically reduce development time.

## Use Cases

Whenever you find yourself copying-and-pasting a group of widgets, you should probably turn it into a Component.

### Example: Product Card

Imagine an E-commerce app. On the "Listing Page", you display a grid of products. Each cell has:

* An Image
* A Title
* A Price Tag
* A "Add to Cart" Button

Instead of building this grid 50 times, you build **one** "Product Card" component. You then place this component 50 times, passing different data (Image, Title, Price) to each instance.

## Anatomy of a Component

Just like a Page, a Component has inputs and internal state.

### 1. Component Arguments (Inputs)

Arguments are the data a component *needs* to function. When you place a component on a page, the builder asks you to provide values for these arguments.

* **Definition**: You define arguments in the **Component Properties** tab.
* **Example**: For `ProductCard`, you would define:
  * `productImage` (Image URL)
  * `productName` (String)
  * `price` (Double)
* **Usage**: Inside the component, you bind these arguments to widgets (e.g., bind `productName` to a Text widget).

### 2. Component State (Internal)

State represents the *internal behavior* of the component that doesn't affect the parent page directly.

* **Definition**: Mutable variables specific to *this instance* of the component.
* **Example**: An `isLiked` toggle or a `quantity` counter inside the card.

> \[!NOTE] Learn more in the [Page & Component State](https://docs.digia.tech/data-and-state/state-management/page-and-component-state) guide.

## Component Lifecycle

Components have a simple lifecycle: **Mount** and **Unmount**.

1. **Mount**: The component is added to the widget tree and painted on the screen.
2. **Unmount**: The component is removed from the widget tree (e.g., scrolled off-screen or part of a conditional builder that turned false).

> \[!IMPORTANT] **No Exposed Lifecycle Actions** Unlike Pages, components **do not** currently expose lifecycle triggers like `OnMount` or `OnDispose` in the builder. You cannot run logic automatically when a component appears. All logic must be triggered by user interaction (e.g., `OnTap`).

## Working in Studio

### Creating a Component

1. **From Scratch**: Go to the **Components Panel**, click **+**, and select **Create Blank Component**.
2. **From Selection**: Select a widget tree on a Page ➝ Right Click ➝ **Extract to Component**. This is the fastest way to componentize existing UI.

### Defining Properties

Once inside the component editor:

1. Select the root or click the background.
2. Go to the **Properties Panel**.
3. Add **Parameters** (Inputs) to define what data this component accepts.