Channel Pinning and Archiving

Channel pinning and archiving let users pin channels to the top or hide them from lists.

Best Practices

Use pinned_at and archived_at from membership to drive UI state reliably.
Keep pin/unpin and archive/unarchive actions idempotent and optimistic.
Filter or sort consistently so pinned channels don’t disappear on updates.
Avoid mixing pinned and archived filters in the same list unless clearly labeled.
Provide clear affordances so users can undo pin/archive actions easily.

Channel Pinning

Pinning moves a channel to the top of the list (when sorted accordingly).

To pin a channel, you can use the channel.pin() method.

await channel.pin();

To unpin a channel, you can use the channel.unpin() method.

await channel.unpin();

Read pinned status via membership.pinned_at from useChannelMembershipState.

An example of how to implement channel pinning is shown below:

import { Pressable } from "react-native";
import {
  Pin,
  Unpin,
  useChannelMembershipState,
} from "stream-chat-react-native";

const CustomChannelPreview = ({ channel }) => {
  const membership = useChannelMembershipState(channel);

  return (
    <Pressable
      onPress={async () => {
        if (membership.pinned_at) {
          await channel.unpin();
        } else {
          await channel.pin();
        }
      }}
    >
      {membership.pinned_at ? (
        <Unpin height={24} width={24} pathFill="red" />
      ) : (
        <Pin size={24} />
      )}
    </Pressable>
  );
};

Channel Archiving

Archiving hides a channel and can be filtered by archived status.

To archive a channel, you can use the channel.archive() method.

await channel.archive();

To unarchive a channel, you can use the channel.unarchive() method.

await channel.unarchive();

Read archived status via membership.archived_at from useChannelMembershipState.

An example of how to implement channel archiving is shown below:

import { Pressable } from "react-native";
import {
  Archive,
  Unarchive,
  useChannelMembershipState,
} from "stream-chat-react-native";

const CustomChannelPreview = ({ channel }) => {
  const membership = useChannelMembershipState(channel);

  return (
    <Pressable
      onPress={async () => {
        if (membership.archived_at) {
          await channel.unarchive();
        } else {
          await channel.archive();
        }
      }}
    >
      {membership.archived_at ? (
        <Unarchive height={24} width={24} pathFill="red" />
      ) : (
        <Archive height={24} width={24} />
      )}
    </Pressable>
  );
};

Filtering Channels

Filter by pinned/archived status using the filters prop on ChannelList.

For archived channels, you can use the archived filter.

const filters = {
  archived: true,
};
<ChannelList filters={filters} />;

For pinned channels, you can use the pinned filter.

const filters = {
  pinned: true,
};
<ChannelList filters={filters} />;

Sorting Channels

Sort by pinned status using the sort prop on ChannelList.

For pinned channels, you can use the pinned_at field.

const sort = [{ pinned_at: -1 }, { last_message_at: -1 }, { updated_at: -1 }];

<ChannelList sort={sort} />;

This sorts by pinned status, then last message date, then updated date.

Custom Channel Background

Hide Channel History For Newly Added Members