
[MAX UI](https://github.com/max-messenger/max-ui) — библиотека React-компонентов для создания мини-приложений в MAX, сторонних суперприложений, а также standalone-приложений. Готовые компоненты библиотеки умеют подстраиваться под разные платформы и устройства

Ознакомьтесь с основными принципами устройства интерфейса, навигации и типографики, а также примерами мини-приложений в нашем гайдлайне — его можно скачать в формате .FIG по [ссылке](https://github.com/max-messenger/max-ui/blob/main/MAXUI-Figma.fig)

## Особенности MAX UI

* **Дизайн-система MAX**Библиотека компонентов разработана на основе дизайн-системы MAX, что позволяет мини-приложениям выглядеть гармонично в интерфейсе цифровой платформы

* **Единообразие на разных платформах**Компоненты библиотеки органично встраиваются в мобильные платформы iOS и Android, а также в экраны устройств разного размера

* **Современный UI Kit**TypeScript, React 19+, полиморфные компоненты и подробная документация с примерами

> Знаете, как улучшить MAX UI? Мы открыты к предложениям:
> - Чтобы сообщить об ошибках в библиотеке, создайте [**New issue**](https://github.com/max-messenger/max-ui/issues) в [репозитории MAX UI](https://github.com/max-messenger/max-ui)
> - Чтобы предложить идею, создайте **Fork** библиотеки и откройте **Pull request**

## Подключение библиотеки MAX UI

Установите библиотеку одной из команд:

npm i @maxhub/max-ui
yarn add @maxhub/max-ui
pnpm add @maxhub/max-ui

Оберните код вашего приложения в провайдер MAX UI и подключите стили:

import { createRoot } from 'react-dom/client';
import { MaxUI } from '@maxhub/max-ui';
import '@maxhub/max-ui/dist/styles.css';
import App from './App.jsx';

const Root = () => (
    
        
    
);

createRoot(document.getElementById('root')).render();

Используйте компоненты библиотеки:

import { Panel, Grid, Container, Flex, Avatar, Typography } from '@maxhub/max-ui';

const App = () => (
    
        
            
                
                    
                        
                    

                    Иван Иванов
                
            
        
    
);

export default App;

---

## Компоненты

Компоненты библиотеки MAX UI мимикрируют под нативные компоненты iOS и Android и умеют поддерживать светлую и тёмную темы оформления. Тема и платформа определяются автоматически в провайдере `MaxUI`, но могут быть переопределены через свойства `platform` (`'ios'` | `'android'`) и `colorScheme` (`'light'` | `'dark'`)

import { createRoot } from 'react-dom/client';
import { MaxUI } from '@maxhub/max-ui';
import '@maxhub/max-ui/dist/styles.css';
import App from './App.jsx';

const Root = () => (
    
        
    
);

createRoot(document.getElementById('root')).render();

---

## Полиморфные компоненты

Полиморфность компонентов реализована через паттерн `asChild` prop: это позволяет предотвратить ошибки типизации и не увеличивать время TypeScript-процессинга

В DOM полиморфные компоненты могут быть представлены в виде разных тегов. Например, компонент `Button` — как `button`, `a`, `span` и так далее

| React-компонент | DOM* |
|---|---|
| `Я — кнопка` | ```  Я — кнопка``` |
| ```  Я — ссылка!``` | ```  Я — ссылка!``` |
| ```  Я — ссылка RRD!``` | ```  Я — ссылка RRD!``` |
| *упрощённое представление компонента |

### Корнер-кейс с asChild

Паттерн `asChild` prop может привести к конфликту свойств, если у одинаковых свойств родительского и дочернего компонентов разные значения. В этом случае свойства `className`, `style` и обработчики событий `on*` (`onClick`, `onChange` и другие) объединяются. В остальных случаях приоритет остаётся у свойств родительского компонента

| React-компонент | DOM* |
|---|---|
| ```  Кнопка``` | ```  Кнопка``` |
| ```  Кнопка``` | ``  style="color: red; background: green">``  Я — кнопка``` |
| *упрощённое представление компонента |

---

## Кастомизация компонентов

ℹ️ Библиотека предоставляет API для кастомизации, но не гарантирует отсутствие изменений в следующих мажорных версиях. Любая кастомизация компонентов — ответственность разработчика мини-приложения

В MAX UI есть два способа кастомизации компонентов — переопределение CSS-переменных и свойство `innerClassNames`

* Переопределение CSS-переменных Все токены дизайн-системы MAX заданы в CSS-переменных. Вы можете переопределить переменные как для конкретного компонента, так и для всей темы в целом

* Свойство `innerClassNames` Многосоставные компоненты, например `Button`, имеют свойство `innerClassNames`. Оно позволяет указать `className` для внутренних элементов

| React-компонент | DOM* |
|---|---|
| `}>``  Кнопка с иконкой``` | ```  ``    ``  ``  Я — кнопка``` |
| `}``  innerClassNames={{ iconBefore: 'my-custom-icon-class' }}>``  Кнопка с иконкой``` | ```  ``    ``  ``  Я — кнопка``` |
| *упрощённое представление компонента |

ℹ️ Если у вас возникли вопросы, [посмотрите раздел с ответами](https://dev.max.ru/help)
