# Broxus / React Components

A React component library that extends `@broxus/react-uikit` with higher-level, composite components for building
web application interfaces.

## Table of Contents

- [Installation](#installation)
- [Components](#components)
  - [Token & Pool](#token--pool)
  - [Data Entry](#data-entry)
  - [Data Display](#data-display)
  - [Charts](#charts)
  - [Utility](#utility)
- [Customization](#customization)
  - [SCSS Entry Points](#scss-entry-points)
  - [Selective Import](#selective-import)
  - [Overriding CSS Custom Properties](#overriding-css-custom-properties)
  - [Hook Mixins](#hook-mixins)

## Installation

Install the package as project dependency

```shell
npm install @broxus/react-components
```

```shell
yarn add @broxus/react-components
```

```shell
pnpm add @broxus/react-components
```

```shell
bun add @broxus/react-components
```

## Components

### Token & Pool

Components for displaying and selecting tokens and liquidity pools.

| Component | Description |
|---|---|
| `TokenIcon` | Token logo image with fallback |
| `TokenBadge` | Token name/symbol badge with icon |
| `TokenAmountBadge` | Token amount display with icon and formatting |
| `TokenSelect` | Token selection dropdown |
| `TokenSelector` | Full token selector with search |
| `TokensList` | Scrollable list of tokens |
| `TokenAmountInput` | Input for token amounts with token selection |
| `PoolSelect` | Liquidity pool selector |
| `PoolTokensBadge` | Overlapping token icons for a pool |

### Data Entry

Specialized input and control components.

| Component | Description |
|---|---|
| `AmountInput` | Numeric amount input with max button and formatting |
| `ComposedControl` | Input with attached label or action (e.g. input + button) |
| `OrderingSwitcher` | Column sort direction toggle |
| `TimeframeSwitcher` | Timeframe period selector (1D, 1W, 1M, etc.) |

### Data Display

Components for presenting formatted data and metrics.

| Component | Description |
|---|---|
| `FormattedTokenAmount` | Formatted token amount with decimals and abbreviation |
| `FormattedCurrencyValue` | Formatted fiat currency value |
| `QuotationRate` | Exchange rate display |
| `QuotationsDelta` | Price change indicator with color (positive/negative) |
| `Stats` | Key-value statistics block |
| `Descriptions` | Labeled description list |
| `Skeleton` | Content placeholder during loading |
| `ContentLoader` | SVG-based animated content placeholder |
| `Copy` | Copy-to-clipboard button with tooltip |
| `Datetime` | Formatted date/time display |
| `RelativeTime` | Relative time label (e.g. "5 min ago") |
| `EcosystemLink` | External link with ecosystem icon |

### Charts

Data visualization components.

| Component | Description |
|---|---|
| `Chart` | Line/area chart |
| `PieChart` | Pie/donut chart with tooltip |

### Utility

Low-level and helper components.

| Component | Description |
|---|---|
| `NativeScrollArea` | Custom-styled native scrollbar container |
| `WalletAccount` | Wallet address display with icon and truncation |
| `AccountIcon` | Generated avatar icon for an address |
| `IconsSet` | SVG icon sprite definitions |
| `Icon` | Icon reference from the sprite |
| `Close` | Close button |
| `Leader` | Dot leader line between two elements |
| `AddAsset` | Button to add a token to wallet |
| `EmptyListPicture` | Empty state illustration |
| `Noop` | No-op render component |

## Customization

The SCSS system follows the same architecture as `@broxus/react-uikit` — see [Customization](https://www.npmjs.com/package/@broxus/react-uikit#customization) for a detailed overview of the two-layer approach (SCSS variables + CSS custom properties), configurable imports, and hook mixins.

### SCSS Entry Points

| Entry point | Purpose |
|---|---|
| `@broxus/react-components/styles/import` | Main entry — outputs component styles with conditional token generation |
| `@broxus/react-components/styles/tokens` | Re-exports token mixins for selective inclusion |

Individual component styles are also available:

```scss
@use '@broxus/react-components/styles/skeleton';
@use '@broxus/react-components/styles/chart';
```

### Selective Import

```scss
@use '@broxus/react-components/styles/import' with (
    $components: (skeleton: true, chart: true, token-icon: true),
);
```

Or include everything:

```scss
@use '@broxus/react-components/styles/import' with (
    $components: (all: true),
);
```

Component map:

| Enabled by default | Disabled by default |
|---|---|
| `amount-input`, `composed-control`, `copy`, `explorer-links`, `ordering-switcher`, `icons-set`, `pool-tokens-badge`, `quotation-delta`, `quotation-rate`, `skeleton`, `stats`, `token-amount-badge`, `token-amount-input`, `token-badge`, `token-icon`, `token-selector`, `tokens-list`, `wallet-account` | `chart`, `content-loader`, `descriptions`, `formatted-currency-value`, `formatted-token-amount`, `native-scroll-area`, `pie-chart`, `pool-select`, `token-select` |

### Overriding CSS Custom Properties

Token mixins accept `@content` blocks:

```scss
@use '@broxus/react-components/styles/tokens';

:root {
    @include tokens.skeleton-tokens {
        --skeleton-background: rgba(255, 255, 255, 8%);
    }
    @include tokens.stats-tokens;
    @include tokens.token-icon-tokens;
}
```

### Hook Mixins

Register hook mixins via the `$mixins` map:

```scss
@use 'sass:meta';
@use 'mixins';

@use '@broxus/react-components/styles/import' as * with (
    $components: (all: true),
    $mixins: (
        'hook-composed-control': meta.get-mixin('hook-composed-control', 'mixins'),
        'hook-stats': meta.get-mixin('hook-stats', 'mixins'),
    ),
);
```