flutter_oembed 1.0.1-alpha

A Flutter package for embedding social media content (X, TikTok, Instagram, Facebook, YouTube, Spotify, Vimeo, and more) using the OEmbed protocol with WebView rendering.

flutter_oembed

Warning

This library is still in development. The API might change in future updates.

Contributions are welcome! Please feel free to raise issues for any bugs you encounter, or submit pull requests with ideas, suggestions, and code improvements.

A Flutter package for embedding rich social and media content with oEmbed APIs and WebView rendering.

Current Package Status

• Current package version: 1.0.0
• Verified platforms: Android, iOS
• Not supported currently: Flutter Web
• Not yet verified for release: macOS, Windows, Linux

Use the current stable line:

dependencies:
  flutter_oembed: ^1.0.0

Features

• Multiple built-in providers: X, TikTok, Instagram, Facebook, Threads, Reddit, YouTube, Vimeo, Dailymotion, Spotify, SoundCloud
• Automatic height adjustment for embedded content
• Built-in response caching
• Direct iframe rendering for selected providers such as YouTube and Spotify
• Per-provider render configuration and custom provider rules
• Debug logging hooks for provider resolution, network requests, and WebView lifecycle

Platform Support

flutter_oembed currently targets mobile Flutter apps that can host a platform WebView.

Platform	Status	Notes
Android	Supported	Verified in the current repo workflow
iOS	Supported	Verified in the current repo workflow
Flutter Web	Not supported	This package relies on webview_flutter; there is no iframe-based web fallback yet
macOS	Unverified	Not part of the current release verification matrix
Windows	Unverified	Not part of the current release verification matrix
Linux	Unverified	Not part of the current release verification matrix

Provider Notes

• Meta providers such as Facebook, Instagram, and Threads require a Meta App ID and Client Token.
• Provider behavior is not uniform. Some providers expose less metadata or more restrictive embed behavior than others.
• The package auto-pauses media when embeds leave the viewport, but there is no stable public media-control API yet.

Brightness Support Matrix

EmbedConfig.brightness is not a universal dark-mode switch. It is only forwarded where the upstream provider or native player path exposes a stable theme setting.

Provider path	brightness support	Notes
X	Supported	Mapped to the theme query parameter
Reddit	Supported	Mapped to the theme=dark query parameter
YoutubeEmbedPlayer	Supported	Mapped to the YouTube player theme setting unless you override theme manually
Facebook / Instagram / Threads	Not supported	Meta oEmbed endpoints do not expose a package-level dark-mode switch here
Spotify	Not supported	Current oEmbed endpoint ignores package brightness
TikTok	Not supported	Current oEmbed and native player integrations do not map brightness
Vimeo	Not supported	Current oEmbed endpoint ignores package brightness
SoundCloud	Not supported	Current oEmbed endpoint ignores package brightness
Dailymotion / Giphy / NYTimes / generic oEmbed providers	Not supported	No package-level brightness mapping is currently implemented

Supported Providers

flutter_oembed ships with verified support for these provider groups:

Category	Providers
Social	X, Facebook, Instagram, Threads, Reddit, TikTok, Tumblr
Video	YouTube, Vimeo, Dailymotion
Audio	Spotify, SoundCloud
Media / News	Flickr, Giphy, The New York Times

Getting Started

Wrap your app in an EmbedScope to provide global configuration:

EmbedScope(
  config: EmbedConfig(
    facebookAppId: 'YOUR_APP_ID',
    facebookClientToken: 'YOUR_CLIENT_TOKEN',
  ),
  child: MyApp(),
)

Then render content with EmbedCard:

EmbedCard(
  url: 'https://twitter.com/X/status/1328842765115920384',
  embedType: EmbedType.x,
  onLinkTap: (url, data) {
    debugPrint('User tapped link: $url');
  },
)

Sizing And Height Constraints

flutter_oembed derives embed height from provider metadata, measured WebView content height, or provider-specific fallbacks. You can override that behavior per embed with EmbedConstraints.

EmbedCard.url(
  'https://open.spotify.com/track/4JOEMgLkrHp8K1XNmyNffH',
  embedConstraints: const EmbedConstraints(
    preferredHeight: 232,
    minHeight: 180,
    maxHeight: 320,
  ),
)

Use preferredHeight when you want a stable initial size. Add minHeight and maxHeight when the embed can resize but should stay within bounds.

embedHeight is still accepted as a legacy shorthand, but new code should use embedConstraints: EmbedConstraints(preferredHeight: ...).

Provider Specific Parameters

You can fine-tune the native player or embed behavior for supported providers using embedParams. This is useful for customizing controls, autoplay behavior, or themes directly at the provider level.

EmbedCard.url(
  'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
  embedParams: const YoutubeEmbedParams(
    controls: true,
    autoplay: false,
    theme: 'dark',
  ),
)

The package provides strongly-typed param classes including:

• YoutubeEmbedParams
• TiktokEmbedParams
• XEmbedParams
• SoundcloudEmbedParams
• MetaEmbedParams
• VimeoEmbedParams

Meta Setup

Facebook, Instagram, and Threads embeds require credentials from Meta for Developers.

References:

• Meta oEmbed Documentation
• Facebook oEmbed API Guide
• Instagram oEmbed API Guide
• Threads oEmbed API Guide

Advanced Configuration

You can customize caching, provider render modes, and style:

EmbedConfig(
  useDynamicDiscovery: true, // Enables searching the official oEmbed registry if no local provider matches
  providers: EmbedProviderConfig(
    providerRenderModes: {
      'YouTube': EmbedRenderMode.iframe,
      'Spotify': EmbedRenderMode.iframe,
    },
  ),
  cache: EmbedCacheConfig(
    enabled: true,
    defaultCacheDuration: Duration(days: 7),
  ),
  style: EmbedStyle(
    borderRadius: BorderRadius.circular(12),
  ),
)

Debug Logging

Enable debug logging when you need visibility into provider resolution, cache hits, network requests, and WebView loading events:

EmbedConfig(
  logger: const EmbedLogger.debug(),
)

You can also forward logs to your own logger:

EmbedConfig(
  onLinkTap: (url, data) {
    debugPrint('Clicked $url on $data');
  },
  logger: EmbedLogger.enabled(
    level: EmbedLogLevel.info,
    sink: ({
      required EmbedLogLevel level,
      required String message,
      Object? error,
      StackTrace? stackTrace,
    }) {
      myLogger.log(
        message,
        level: level.name,
        error: error,
        stackTrace: stackTrace,
      );
    },
  ),
)

HTML And Markdown Integration

The repository example app includes working integrations for:

• markdown_widget
• flutter_html
• Quill-based editors

See the example app in /example for concrete integration code.

Troubleshooting

• If Meta embeds fail, verify your App ID and Client Token first.
• If a provider resolves but renders an empty frame, enable debug logging and inspect WebView/network events.
• If a URL is not matched, provide a custom provider rule or enable dynamic discovery where appropriate.
• If you need Flutter Web support, this package does not provide it yet.

Additional Information

• pub.dev: https://pub.dev/packages/flutter_oembed
• Example app: /example
• Release checklist: RELEASE_CHECKLIST.md