# 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](/data-and-state/state-management/page-and-component-state.md) 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.


---

# Agent Instructions: 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:

```
GET https://docs.digia.tech/ui-building-blocks/components.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.