# TGUI Angular
Comprehensive Angular UI library for building Telegram Web Apps with modern components and theming support.
## TON Society Bounty
This project is being developed as part of the TON Society bounty program:
- [Initial Bounty Proposal](https://github.com/ton-society/grants-and-bounties/issues/606)
- [Development Bounty](https://github.com/ton-society/grants-and-bounties/issues/1077)
## Installation
```bash
npm install tgui-angular
```
## Importing Styles
To use TGUI Angular components with proper styling, you need to import the library's CSS files. Choose one of the methods below:
### Method 1: Via angular.json (Recommended)
Add the styles to your `angular.json` file:
```json
{
"projects": {
"your-app": {
"architect": {
"build": {
"options": {
"styles": [
"src/styles.css",
"node_modules/tgui-angular/styles/index.css"
]
}
}
}
}
}
}
```
**Note:** Thanks to package.json exports, you can also use the shorter path in CSS imports (but angular.json requires the full path).
### Method 2: Via styles.css
Import the styles in your main `src/styles.css` file:
```css
/* Full styles import */
@import 'tgui-angular/styles';
/* Or explicitly specify the file */
@import 'tgui-angular/styles/index.css';
/* Your custom styles */
```
### Method 3: Import Only Variables
If you only need the CSS variables for custom styling:
```css
@import 'tgui-angular/styles/variables.css';
/* Your custom components using TGUI variables */
.my-component {
background-color: var(--tgui--bg_color);
color: var(--tgui--text_color);
padding: var(--tgui--text--line_height);
}
```
### Available Style Files
- **`index.css`** - Complete styles (includes variables + utility classes)
- **`variables.css`** - Only CSS custom properties for theming
## Quick Start
### Standalone Application Setup (Recommended)
```typescript
// app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideRouter } from '@angular/router';
export const appConfig: ApplicationConfig = {
providers: [
// Your other providers
]
};
// main.ts
import { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app/app.component';
import { appConfig } from './app/app.config';
bootstrapApplication(AppComponent, appConfig);
```
```typescript
// app.component.ts
import { Component } from '@angular/core';
import { RootComponent } from 'tgui-angular';
@Component({
selector: 'app-root',
standalone: true,
imports: [RootComponent],
template: `
Hello Telegram Web App!
`
})
export class AppComponent {}
```
## Core Components
### Root Component
The `tgui-root` component is required and serves as the foundation for your app:
```html
```
**Features:**
- Automatic theme detection (light/dark)
- Platform-specific styling (iOS/base)
- CSS variables injection
- Portal container for overlays
## Available Components
### Blocks (UI Building Blocks)
```typescript
import {
BadgeComponent,
ButtonComponent,
AvatarComponent,
AvatarStackComponent,
SectionComponent,
CardComponent,
IconButtonComponent,
ImageComponent,
ImageBadgeComponent,
IconContainerComponent,
PlaceholderComponent,
ListComponent,
StepsComponent,
TimelineComponent,
TimelineItemComponent,
AccordionComponent,
AccordionSummaryComponent,
AccordionContentComponent
} from 'tgui-angular';
```
### Typography
```typescript
import {
TypographyComponent,
CaptionComponent,
HeadlineComponent,
LargeTitleComponent,
SubheadlineComponent,
TextComponent,
TitleComponent
} from 'tgui-angular';
```
### Form Components
```typescript
import {
ChipComponent,
FormInputComponent,
FormInputTitleComponent,
InputComponent,
CheckboxComponent,
ColorInputComponent,
RadioComponent,
FileInputComponent,
PinInputComponent,
RatingComponent,
SelectComponent,
SwitchComponent,
TextareaComponent
} from 'tgui-angular';
```
### Feedback Components
```typescript
import {
SpinnerComponent,
SpoilerComponent,
SkeletonComponent,
ProgressComponent,
CircularProgressComponent
} from 'tgui-angular';
```
### Navigation Components
```typescript
import {
BreadcrumbsComponent,
BreadcrumbsItemComponent,
LinkComponent
} from 'tgui-angular';
```
### Utility Components
```typescript
import {
TappableComponent,
RippleComponent,
RootPortalComponent,
TouchComponent,
RootRendererComponent
} from 'tgui-angular';
```
## Services
### Theme Service
```typescript
import { Component } from '@angular/core';
import { ThemeService, AppearanceType } from 'tgui-angular';
@Component({
selector: 'app-example',
template: `
`
})
export class ExampleComponent {
currentTheme: AppearanceType = 'light';
constructor(private themeService: ThemeService) {
// Listen to theme changes
this.themeService.appearance$.subscribe(theme => {
this.currentTheme = theme;
});
}
toggleTheme() {
const newTheme = this.currentTheme === 'light' ? 'dark' : 'light';
this.themeService.setAppearance(newTheme);
}
}
```
### Platform Service
```typescript
import { Component } from '@angular/core';
import { PlatformService, PlatformType } from 'tgui-angular';
@Component({
selector: 'app-example',
template: `