> For the complete documentation index, see [llms.txt](https://docs.feedspring.com/introduction/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.feedspring.com/introduction/feeds/tiktok.md).

# TikTok

Display TikTok videos with thumbnails, inline playback, engagement counts and profile data.

Use FeedSpring to display TikTok videos on your site, thumbnails, playable video, engagement counts, and profile information.

Feed ID prefix: `tiktok_...`

### Render TikTok with

* [Attributes](/introduction/attributes/overview.md), add TikTok to any HTML page
* [React & Next.js](/introduction/build-with/react-nextjs.md), use the GraphQL API or attributes in a React app
* [Framer](/introduction/build-with/framer.md), use the TikTok component in Framer
* [GraphQL API](#graphql-api), fetch TikTok data directly — see the query below

### Post fields

In the GraphQL API, post fields are on each item in `videos.nodes`.

| Attribute                    | GraphQL field     | Type              | Description                                                                                                          |
| ---------------------------- | ----------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------- |
| `feed-field="img"`           | `cover.url`       | image URL         | The video thumbnail. Sets the `src` of an `<img>`.                                                                   |
| `feed-field="video"`         | `embedUrl`        | derived embed URL | Inline video player. Sets the `src` of an `<iframe>` to the TikTok embed URL.                                        |
| `feed-field="link"`          | `url`             | URL               | Canonical TikTok link. Sets the `href` of an `<a>`.                                                                  |
| `feed-field="title"`         | `title`           | string            | Video title. Written with `innerHTML`.                                                                               |
| `feed-field="description"`   | `description`     | string            | Video description. Written with `innerHTML`.                                                                         |
| `feed-field="duration"`      | `durationSeconds` | number            | Video length.                                                                                                        |
| `feed-field="view-count"`    | `viewCount`       | number            | View count, formatted with compact locale notation (e.g. `1.2K`).                                                    |
| `feed-field="like-count"`    | `likeCount`       | number            | Like count, formatted with compact locale notation.                                                                  |
| `feed-field="comment-count"` | `commentCount`    | number            | Comment count, formatted with compact locale notation.                                                               |
| `feed-field="share-count"`   | `shareCount`      | number            | Share count.                                                                                                         |
| `feed-field="timestamp"`     | `publishedAt`     | date-time         | When the video was published. See [timestamp formatting](/introduction/attributes/special-fields.md#feed-timestamp). |

### Profile fields

In the GraphQL API, profile fields are on the feed itself.

| Attribute                      | GraphQL field            | Type         | Description                                                                                                                        |
| ------------------------------ | ------------------------ | ------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `feed-field="avatar"`          | `profile.avatar.url`     | image URL    | Profile avatar.                                                                                                                    |
| `feed-field="name"`            | `profile.displayName`    | string       | Profile display name. Written with `innerHTML`.                                                                                    |
| `feed-field="bio"`             | `profile.bio`            | string       | Profile bio. Written with `innerHTML`.                                                                                             |
| `feed-field="profile-link"`    | `profile.url`            | URL          | Link to the profile on TikTok. Sets the `href` of an `<a>`. See the known issue below.                                             |
| `feed-field="follower-count"`  | `profile.followerCount`  | number       | Total followers, formatted with compact locale notation.                                                                           |
| `feed-field="following-count"` | `profile.followingCount` | number       | Total accounts followed, formatted with compact locale notation.                                                                   |
| `feed-field="total-likes"`     | `profile.likeCount`      | number       | Total likes across all the account's videos, formatted with compact locale notation.                                               |
| `feed-field="verified"`        | `profile.isVerified`     | boolean gate | Element is kept in the DOM if the account is verified, removed entirely if not. Use this to conditionally render a verified badge. |

### Inline video playback

TikTok has a dedicated `video` attribute that renders the video inline using TikTok's embed player. Apply it to an `<iframe>`:

```html
<div feedspring="post">
  <iframe feed-field="video" allowfullscreen></iframe>
</div>
```

FeedSpring sets the `src` to `https://www.tiktok.com/embed/v2/{video-id}`. The TikTok player handles all controls, audio, and fullscreen behaviour.

If you prefer to link out instead of embedding, use `feed-field="link"` on an `<a>` and show the thumbnail with `feed-field="img"`. This is lighter-weight and faster to render.

### Verified badge

The `verified` attribute works as a conditional gate. Place it on any element that should only show for verified accounts, and FeedSpring removes the element for unverified ones:

```html
<header>
  <img feed-field="avatar" alt="" />
  <span feed-field="name"></span>
  <svg feed-field="verified"><!-- blue checkmark icon --></svg>
</header>
```

{% hint style="warning" %}
**Known issue:** `feed-field="profile-link"` does not currently work. The TikTok script registers the field with a trailing space, so only `feed-field="profile-link "` matches. A fix is in progress; until then, link to the profile with a static URL.
{% endhint %}

### TikTok-specific notes

* **9:16 is native.** TikTok videos are always portrait 9:16. Layouts that crop to square or landscape will look wrong. Respect the aspect ratio in your CSS.
* **`title` and `description` may be identical.** TikTok uses both fields, often populated with the same value (the video caption). Most layouts use one or the other.
* **Inline video loads the TikTok player.** Using `feed-field="video"` pulls in TikTok's embed script, which adds weight to the page. For performance-sensitive pages, use thumbnails with click-through links instead.
* **`duration` is a raw number.** Format it yourself if you want `0:15` style output.

### Example

A video grid using the attributes delivery method:

```html
<section feedspring="tiktok_YOUR-FEED-ID" feed-options="render:dynamic|limit:8">
  <header>
    <img feed-field="avatar" alt="" />
    <span feed-field="name"></span>
    <span feed-field="follower-count"></span> followers
  </header>

  <div class="grid">
    <article feedspring="post">
      <img feed-field="img" alt="" />
      <div class="meta">
        <span feed-field="view-count"></span> views
      </div>
      <a feed-field="link" target="_blank" rel="noopener">Watch on TikTok</a>
    </article>
  </div>
</section>
```

### GraphQL API

Fetch TikTok feeds with the [GraphQL API](/introduction/graphql-api/overview.md). The feed returns `TikTokFeedData`, with items under `videos.nodes`.

TikTok feeds contain profile information and a list of videos.

```graphql
query TikTokFeed($publicKey: String!) {
  feed(publicKey: $publicKey) {
    __typename
    ... on TikTokFeedData {
      profile {
        id
        avatar {
          url(input: { width: 160, height: 160 })
        }
        displayName
        bio
        url
        followingCount
        likeCount
        isVerified
        followerCount
      }
      videos {
        nodes {
          id
          url
          embedUrl
          embedHtml
          cover {
            url(input: { width: 800 })
          }
          title
          description
          publishedAt
          viewCount
          likeCount
          shareCount
          commentCount
          durationSeconds
        }
      }
    }
  }
}
```

#### Field notes

| Field             | Description                                                                                        |
| ----------------- | -------------------------------------------------------------------------------------------------- |
| `profile`         | Profile represented by the feed.                                                                   |
| `videos.nodes`    | Videos in the order configured by FeedSpring. The list is always present and may be empty.         |
| `url`             | Public TikTok URL for the profile or video.                                                        |
| `embedUrl`        | URL intended for embedding the video.                                                              |
| `embedHtml`       | Embed markup supplied for the video. Treat it as third-party HTML before inserting it into a page. |
| `cover`           | Optional video cover image.                                                                        |
| `publishedAt`     | Publication time, or `null` when unavailable.                                                      |
| `durationSeconds` | Video duration in seconds.                                                                         |

### Typical use cases

* Creator homepage video grids
* Brand campaign landing pages
* Product reveal pages with inline playback
* Event or launch highlight feeds

### Next steps

* [Choose your setup](/introduction/getting-started/choose-your-setup.md) to render TikTok
* [Feed Options](/introduction/attributes/feed-options.md) for `limit` and `skip`, and [Filtering](/introduction/core-concepts/filtering.md) for dashboard filters
* [Browse other feed sources](/introduction/getting-started/readme.md#what-this-documentation-covers)