Widget Preview Documentation and PreviewThemeData API are out-of-sync

[maranix]

On official Flutter Documentation for widget previews the APIs mentioned for providing custom theme data to widget preview is not accurate.

Filter previews by selected file in IDEs: Example flutter/flutter#1
Create custom preview annotations: Example flutter/flutter#2

Both of these examples describe the API for PreviewThemeData to be something like this:

PreviewThemeData(
      materialLight: ThemeData.light(),
      materialDark: ThemeData.dark(),
  );

However as of Flutter 3.47 according to api.flutter.dev#PreviewThemeData the PreviewThemeData is mentioned as a zero argument interface.

This is a massive disconnect between what is shown and what is currently available. There are many other similar examples showcasing the same usage.

[!] Flutter (Channel stable, 3.47.0, on macOS 15.7.8 24G812 darwin-x64, locale en-IN) [2.8s]
    ! Flutter is deprecating support for Intel-based Macs. A future version of Flutter will require an Apple Silicon Mac to
      build applications.
    • Flutter version 3.47.0 on channel stable at /opt/maranix/flutter
    • Upstream repository https://github.com/flutter/flutter.git
    • Framework revision 4cf2416426 (7 days ago), 2026-08-11 11:53:49 -0700
    • Engine revision 5f77625673
    • Dart version 3.13.0
    • DevTools version 2.60.0
    • Feature flags: enable-web, enable-linux-desktop, enable-macos-desktop, enable-windows-desktop, enable-android,
      enable-ios, cli-animations, enable-native-assets, enable-record-use, enable-swift-package-manager,
      omit-legacy-version-file, enable-lldb-debugging, enable-uiscene-migration
    • If those were intentional, you can disregard the above warnings; however it is recommended to use "git" directly to
      perform update checks and upgrades.

[✓] Android toolchain - develop for Android devices (Android SDK version 37.0.0) [11.6s]
    • Android SDK at /opt/maranix/Android/Sdk
    • Emulator version unknown
    • Platform android-37.0, build-tools 37.0.0
    • ANDROID_HOME = /opt/maranix/Android/Sdk/
    • Java binary at: /usr/bin/java
      This JDK was found in the system PATH.
      To manually set the JDK path, use: `flutter config --jdk-dir="path/to/jdk"`.
    • Java version OpenJDK Runtime Environment Temurin-25.0.4+7 (build 25.0.4+7-LTS)
    • All Android licenses accepted.

[✓] Xcode - develop for iOS and macOS (Xcode 26.2) [9.8s]
    • Xcode at /Applications/Xcode.app/Contents/Developer
    • Build 17C52
    • CocoaPods version 1.16.2

[✓] Chrome - develop for the web [647ms]
    • Chrome at /Applications/Google Chrome.app/Contents/MacOS/Google Chrome

[✓] Connected device (3 available) [13.1s]
    • Raman’s iPhone (wireless) (mobile) • 00008120-00025DDE14C3A01E • ios            • iOS 26.6 23G71
    • macOS (desktop)                    • macos                     • darwin-x64     • macOS 15.7.8 24G812 darwin-x64
    • Chrome (web)                       • chrome                    • web-javascript • Google Chrome 151.0.7922.138
    ! Unexpected failure parsing device information from adb output:
      adb-1603546865001HB-2xZ2LU._adb-tls-connect._tcp device product:2127i model:V2142 device:2127 transport_id:1
      Please report a bug at https://github.com/flutter/flutter/issues.

[✓] Network resources [1,325ms]
    • All expected network resources are available.

! Doctor found issues in 1 category.

[puneetkukreja98]

@maranix Thanks for reporting this issue.

Findings: The documentation is out of sync with the current API.

[Piinks]

cc @bkonyi what team-* label is the right label for this issue?

[puneetkukreja98]

I think this issue should be transferred to flutter/website.

[Piinks]

Transferred, thanks!