tdesign-flutter

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

🔨 Installation

SDK Requirements

dart: ">=3.8.0 <4.0.0"
flutter: ">=3.32.0"

Add Dependency

Add the following to your pubspec.yaml:

dependencies:
  tdesign_flutter: 1.0.0-alpha.1

Import

import 'package:tdesign_flutter/tdesign_flutter.dart';

📖 Usage

Theme Configuration

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

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

// Colors
TTheme.of(context).brandNormalColor

// Fonts
TTheme.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": {
      "brandNormalColor": "#D7B386"
    },
    "font": {
      "fontBodyMedium": {
        "size": 40,
        "lineHeight": 55
      }
    }
  }
}
''';

MaterialApp(
  theme: ThemeData(
    extensions: [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.

Note: Since v0.2.6, the Theme Generator supports "Dark Mode". See Dark Mode for details.

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 css2JsonTheme.dart with your file name, theme name, and output path to generate a theme.json file.

3. Apply: Load the theme JSON into TTheme, and your beautiful custom theme is ready.

var jsonString = await rootBundle.loadString('assets/theme.json');
var _themeData = TThemeData.fromJson('green', jsonString);
// ...
MaterialApp(
  title: 'TDesign Flutter Example',
  theme: ThemeData(
    extensions: [_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: _themeData.systemThemeDataLight,
  darkTheme: _themeData.systemThemeDataDark,
  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 TTheme.setResourceBuilder.

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.
      TTheme.setResourceBuilder((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:

Platform	Repository
Vue 2.x	tdesign-vue
Vue 3.x	tdesign-vue-next
React	tdesign-react
Vue 3.x Mobile	tdesign-mobile-vue
React Mobile	tdesign-mobile-react
WeChat Miniprogram	tdesign-miniprogram

🤝 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.