> ## Documentation Index
> Fetch the complete documentation index at: https://learn.social.plus/llms.txt
> Use this file to discover all available pages before exploring further.

# Discovery Widget

> Bring topic-based community conversations to your app's browsing surfaces with a ready-made carousel.

**Discovery Widget brings topic-based content discovery to the pages people already visit.** It helps brands and community teams surface relevant conversations on homepages, category pages, and other browsing surfaces, so users can discover the value of a community without first searching for it.

Your team configures a topic in the social.plus Console, then your app uses that topic's ID to display recommended community posts. Post previews and reaction and comment counts help readers decide what to explore. Your app controls where a selected post opens, providing a route into the conversation and community.

<Info>
  Discovery Widget is supported on **iOS**, **Android**, and **Web**. Flutter and React Native are not supported.
</Info>

## How it works

The widget fetches an ordered selection of posts for its configured topic and displays them in a read-only carousel. Readers can browse previews and select a card. Reacting, commenting, voting, and media playback happen outside the widget, at the destination your app provides.

Recommendations use topic relevance as the main signal, with post engagement and freshness helping order relevant conversations. They are based on the topic rather than the reader's personal interests. Eligibility rules and viewer-specific restrictions, such as blocked authors, can affect which posts appear. See [Topic-based content discovery](/social-plus-sdk/social/discovery-engagement/feed/curated-content) for the SDK integration.

## Before you start

Configure a topic in the social.plus Console and obtain its topic ID. Set up your app's UIKit integration and establish a [user session](/social-plus-sdk/getting-started/authentication) or a [visitor session](/social-plus-sdk/getting-started/visitor-mode) before displaying the widget.

Choose where a card should open in your app, such as a post detail page or your hosted community.

## Embed the widget

Pass a topic ID and handle card selection with `onCardClick`.

<CodeGroup>
  ```tsx Web theme={null}
  import { AmityDiscoveryWidgetComponent } from '@amityco/ui-kit';

  <AmityDiscoveryWidgetComponent
    topicId="your-topic-id"
    onCardClick={(topicId, post) => {
      // Navigate to the selected post in your app.
    }}
  />
  ```

  ```swift iOS theme={null}
  AmityDiscoveryWidgetComponent(
      topicId: "your-topic-id",
      onCardClick: { topicId, post in
          // Navigate to the selected post in your app.
      }
  )
  ```

  ```kotlin Android theme={null}
  AmityDiscoveryWidgetComponent(
      topicId = "your-topic-id",
      onCardClick = { topicId, post ->
          // Navigate to the selected post in your app.
      },
  )
  ```
</CodeGroup>

### Parameters

| Parameter                | Type                     | Default       | Platforms         | Description                                                                                    |
| ------------------------ | ------------------------ | ------------- | ----------------- | ---------------------------------------------------------------------------------------------- |
| `topicId`                | string                   | Required      | iOS, Android, Web | The topic ID configured in the Console.                                                        |
| `showHeader`             | boolean                  | `true`        | iOS, Android, Web | Show the topic heading and navigation controls where supported.                                |
| `minVisibilityThreshold` | number                   | `3`           | iOS, Android, Web | Minimum number of renderable posts needed to show the widget. Values below 1 are clamped to 1. |
| `onCardClick`            | callback                 | None          | iOS, Android, Web | Receives the topic ID and selected post. Overrides the behavior class for this instance.       |
| `pageId`                 | `PageId?` / string       | `nil` / `'*'` | iOS, Web          | Page identifier for customization scoping.                                                     |
| `pageScope`              | `AmityComposePageScope?` | `null`        | Android           | Compose page scope for customization.                                                          |
| `modifier`               | `Modifier`               | `Modifier`    | Android           | Standard Compose modifier.                                                                     |

## Display behavior

The widget adapts to compact and expanded layouts. Readers swipe through cards; Web and Android also provide navigation arrows in the expanded layout.

The widget renders nothing when the request fails or the number of renderable posts is below `minVisibilityThreshold`. It shows no heading, empty state, or error message in these cases. Avoid a separate decorative container that would remain visible when the widget hides.

### Host container

The widget sizes itself from its content and does not set a height on its parent. Place it in a container that fits it:

* Use a wrap-content container, or give the container a minimum height that fits the widget. A shorter container clips the cards, starting with the reaction and comment counts at the bottom.
* Avoid a container with zero or undefined height. The widget still loads posts and reports its impression, but readers can't see it.
* Place the widget in a vertically scrolling or non-scrolling container. A horizontally scrolling parent is not supported, because the widget's own horizontal scrolling competes with it for swipes.

### Supported content

| Post type          | Display                                        |
| ------------------ | ---------------------------------------------- |
| Text               | Text preview                                   |
| Image              | First attachment preview                       |
| Video or clip      | First attachment preview with a play indicator |
| Poll               | Read-only results preview                      |
| Livestream or room | Not rendered                                   |

Unsupported posts do not count toward the visibility threshold. For example, a response with four posts, including two unsupported posts, has only two renderable posts and remains hidden at the default threshold.

Each card shows author and community information, a content preview, and reaction and comment counts. A card is one tap target: mentions, hashtags, links, and preview labels do not have separate actions. Media does not play inside the card, and readers cannot vote in a poll preview.

## Handle card selection

Use `onCardClick` for navigation specific to one placement. For app-wide navigation, override the platform's behavior class instead:

| Platform | Behavior                                                                        |
| -------- | ------------------------------------------------------------------------------- |
| Web      | `AmityDiscoveryWidgetComponentBehavior.goToDestination({ topicId, post })`      |
| Android  | `AmityDiscoveryWidgetComponentBehavior.goToDestination(context, topicId, post)` |
| iOS      | `AmityDiscoveryWidgetComponentBehavior.goToDestination(context)`                |

When `onCardClick` is provided, the behavior class is not called for that instance.

<Note>
  No platform has a default destination. If you provide neither `onCardClick` nor a behavior override, selecting a card does nothing. Provide a navigation handler so a card opens the intended content.
</Note>

## Analytics

The widget automatically reports its impression, visible post-card impressions, and card clicks. It reports each impression once per page load and reports clicks when readers select cards. You do not need to call the SDK analytics methods again for the widget.

If you build a custom discovery surface with the SDK, report these interactions yourself. See [Report interactions](/social-plus-sdk/social/discovery-engagement/feed/curated-content#report-interactions).

## Customization

Use component parameters to control the topic, header, visibility threshold, and card navigation. The widget uses your app's UIKit theme. See [UIKit customization](/uikit/customization/overview) for general theming guidance.

## Build your own discovery surface

Use the [SDK's topic-based content discovery APIs](/social-plus-sdk/social/discovery-engagement/feed/curated-content) when you need a presentation other than the ready-made carousel. They return standard post objects and topic analytics handles so your app can render recommendations and measure interactions.