English | 简体中文

TDesign Flutter is a cross-platform UI component library based on Tencent's design system. Built with the Flutter framework, it enables rapid development of beautiful, consistent mobile/web applications with rich pre-built components and theme customization capabilities, supporting iOS, Android, and Web platforms.

🎉 Features

• Provides Flutter UI component library following TDesign design specifications
• Supports theme customization to match your App's design style
• Includes a comprehensive Icon library with custom replacement support
• Defines color groups according to TDesign specifications (viewable in TColors)
• Real-time preview of default color values through the color declaration class

📱 Preview

Android: Scan the QR code to download the preview app

Download link: tdesign-flutter-example.apk

iOS: Run the project to preview

https://github.com/Tencent/tdesign-flutter/tree/main/tdesign-component

🚀 Quick Start

Requires Flutter ≥ 3.32.0 and Dart ≥ 3.8.0.

Add Dependency

The single-import feature has not been published to pub.dev yet. Before release, add this source dependency pinned to a specific commit to pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  tdesign_flutter:
    git:
      url: https://github.com/Tencent/tdesign-flutter.git
      ref: 86c37e563039c57cf6c3f9b52fead418fd3c03bd
      path: tdesign-component

Once a stable 1.0.0 release containing this feature is published, replace the source dependency with tdesign_flutter: ^1.0.0. This allows compatible 1.x updates without editing the version for every release; 1.0.0 without ^ allows only that exact version. Until then, use the source configuration above.

Install the dependency:

flutter pub get

Minimal Import

import 'package:tdesign_flutter/tdesign_flutter.dart';

The TDesign entry point re-exports Flutter Material widgets, so the same import provides MaterialApp, Scaffold, Text, and TDesign components.

Minimal Usage

Add the button to the widget tree of an existing page:

const TButton(child: Text('Button'))

No additional initialization or theme configuration is required. Omitting onPressed leaves the button disabled.

📖 Usage

Theme Configuration

Configure theme styles (colors, font sizes, font styles, corner radius, shadows) through JSON files. Retrieve theme data using context.tTheme or TThemeData.defaultData().

Recommendation: Use context.tTheme for components that should follow the local theme. Only use TThemeData.defaultData() for components that don't need to follow local themes.

// Colors
context.tTheme.brandColor

// Fonts
TThemeData.defaultData().fontBodyLarge

Icons

TDesign icons are in TTF format and do not follow the theme:

Icon(TIcons.activity)

🎨 Custom Theme

TDesign Flutter provides two flexible theming approaches:

Method 1: JSON Configuration

Define theme properties directly in JSON format:

String themeConfig = '''
{
  "myTheme": {
    "color": {
      "brandColor": "#D7B386"
    },
    "font": {
      "fontBodyMedium": {
        "size": 40,
        "lineHeight": 55
      }
    }
  }
}
''';

MaterialApp(
  theme: TThemeBuilder.light(TThemeData.fromJson('myTheme', themeConfig)!),
  // ...
)

For all available theme keys, see t_default_theme.dart

Method 2: Theme Generator (Recommended)

If you don't want to customize too many colors but still want a beautiful custom theme, the "Theme Generator" is a great choice.

The Theme Generator supports light and dark configurations. See Dark Mode.

1. Generate: Visit TDesign Theme Generator, click the theme generator below, select your desired colors in the generator on the right, and click download.

2. Convert: You will get a theme.css file. Place it in tdesign-component/example/shell/theme/, modify css2_json_theme.dart with your file name, theme name, and output path to generate a theme.json file.

3. Apply: Load the theme JSON with TThemeData.fromJson, and your beautiful custom theme is ready.

var jsonString = await rootBundle.loadString('assets/theme.json');
final _themeData = TThemeData.fromJson('green', jsonString, darkName: 'greenDark') ??
    TThemeData.defaultData();
// ...
MaterialApp(
  title: 'TDesign Flutter Example',
  theme: TThemeBuilder.light(_themeData),
  home: MyHomePage(title: 'TDesign Flutter Components'),
);

Dark Mode Support

Theme configurations generated by the Theme Generator support dark mode colors by default.

// ...
// Set three properties in MaterialApp as follows. If you have custom theme properties, you can modify them using the copyWith() method.
// Note: Theme switching needs to be implemented by the business side, e.g., using Provider. See tdesign-flutter/tdesign-component/example/lib/component_test/dark_test.dart for reference.
MaterialApp(
  theme: TThemeBuilder.light(_themeData),
  darkTheme: TThemeBuilder.dark(_themeData),
  themeMode: themeModeProvider.themeMode,
  // ...
)

🌍 Internationalization

TDesign Flutter does not have built-in internationalization, but supports integration with Flutter's i18n capabilities. You can extend the TResourceDelegate class, which abstracts all text resources inside the components, override the methods to get text for internationalization, and inject it via setTResourceBuilder.

Quick Setup

1. Override TResourceDelegate class:

/// Internationalization resource delegate
class IntlResourceDelegate extends TResourceDelegate {
  IntlResourceDelegate(this.context);

  BuildContext context;

  /// Internationalization requires updating context each time
  updateContext(BuildContext context) {
    this.context = context;
  }

  @override
  String get cancel => AppLocalizations.of(context)!.cancel;

  @override
  String get confirm => AppLocalizations.of(context)!.confirm;
}

2. Inject TResourceDelegate class:

var delegate = IntlResourceDelegate(context);
return MaterialApp(
  home: Builder(
    builder: (context) {
      // Set the text delegate. Internationalization only takes effect after MaterialApp is initialized, and context needs to be updated each time.
      setTResourceBuilder((context) => delegate..updateContext(context), needAlwaysBuild: true);
      return MyHomePage(
        title: AppLocalizations.of(context)?.components ?? '',
      );
    },
  ),
  // Set internationalization
  locale: locale,
  supportedLocales: AppLocalizations.supportedLocales,
  localizationsDelegates: AppLocalizations.localizationsDelegates,
);

3. For Flutter internationalization configuration, please refer to the official documentation: Internationalizing Flutter apps

🔗 More Examples

For more usage examples, refer to example/lib/page/

🌐 TDesign Component Libraries

TDesign provides component libraries for other platforms and frameworks:

🤝 Contributing

Contributions are welcome! Please read the contributing guidelines before submitting your Pull Request.

💬 Feedback

Create GitHub Issues or scan the QR code to join our user groups:

🙏 Acknowledgements

TDesign Flutter depends on the following component libraries. We appreciate the authors for their open-source contributions:

• easy_refresh
• flutter_slidable
• image_picker

📄 License

TDesign Flutter is licensed under the MIT License.