# Overview

The `@blocklet/ui-react` library provides a collection of essential React components designed to accelerate the development of applications, known as Blocklets. It streamlines the creation of common user interface elements by intelligently using the blocklet's metadata, enabling developers to build consistent and feature-rich UIs with minimal effort.

This library is built upon `@arcblock/ux`, which is a themed extension of Material-UI. This foundation ensures that all components are robust, accessible, and easily customizable to fit your application's branding.

## The Problem It Solves

Modern web applications often require a standard set of UI components for layout, user management, and notifications. Implementing these from scratch for every project is time-consuming and can lead to inconsistencies. The Blocklet UI React library addresses this by providing pre-built components that automatically configure themselves based on your blocklet's metadata (`blocklet.yml`).

This metadata-driven approach means that elements like your application's name, logo, navigation links, and theme colors are automatically applied across components, drastically reducing boilerplate code and ensuring brand consistency.

## Core Architecture

The library's architecture is designed for simplicity and automation. When a component like `Header` or `Footer` is rendered, it reads configuration data from the `window.blocklet` object, which is populated by the Blocklet Server from your `blocklet.yml` file. This allows you to define your UI's structure and branding in a central configuration file, and the components adapt accordingly.

<!-- DIAGRAM_IMAGE_START:architecture:16:9:1765962229 -->
![Overview](assets/diagram/overview-diagram-0.jpg)
<!-- DIAGRAM_IMAGE_END -->

## Key Features

-   **Metadata-Driven:** Automatically configures components like `Header` and `Footer` using your blocklet's name, logo, and navigation structure defined in `blocklet.yml`.
-   **Integrated Session Management:** Components seamlessly integrate with DID Connect sessions, automatically displaying user profile information, session controls, and role-based access to navigation links.
-   **Responsive Layouts:** Includes powerful layout components like `Dashboard` that provide a responsive structure for administrative interfaces out of the box.
-   **Component Management:** Offers tools like `ComponentInstaller` and `BlockletStudio` to help manage dependencies and resources within the Blocklet ecosystem.

## Core Components

The library is organized into several key modules, each addressing a specific area of application UI.

<x-cards data-columns="2">
  <x-card data-title="Layout" data-icon="lucide:layout-template" data-href="/components/layout">
    Primary components like Header, Footer, and Dashboard that form the main structure of a blocklet application.
  </x-card>
  <x-card data-title="User Management" data-icon="lucide:users" data-href="/components/user-management">
    A suite of components for handling user profiles, session management, and organization switching.
  </x-card>
  <x-card data-title="Component Management" data-icon="lucide:box" data-href="/components/component-management">
    Tools for dynamically installing, publishing, and managing blocklet components within an application.
  </x-card>
  <x-card data-title="Utilities" data-icon="lucide:wrench" data-href="/components/utilities">
    A collection of helper components and utilities, such as a versatile Icon component and theme providers.
  </x-card>
</x-cards>

## Summary

By leveraging the `@blocklet/ui-react` library, you can significantly reduce development time and focus on your application's unique features. The metadata-driven approach ensures consistency and simplifies the management of common UI elements.

To start building your application, proceed to the [Getting Started](./getting-started.md) guide for a step-by-step tutorial on installing the library and rendering your first components.