Poll components

Poll renders the poll of a message. It provides PollContext and renders the poll's content: the question, the options and the buttons. MessageContent renders it for every message with a poll_id, with the poll from client.polls.fromState(message.poll_id). CreatePoll is the form that creates a poll from the composer. Polls explains how polls are created, voted on and kept current.

Best practices

• Read live poll data from poll.state, with usePollState() or useStateStore(poll.state, selector). message.poll is only the copy that came with the message.
• Replace parts through the override keys below, and keep Poll, which provides the context.
• Render poll parts inside a message, in a Channel or a Thread. The vote button reads the user's capabilities from the channel, and the buttons read the poll and the message from PollContext.
• To show the poll's screens in your navigation instead of in modals, pass onPress to the buttons, as Change the buttons shows. Render the screen's component, such as PollResults, with the message and poll it receives.
• Keep option texts short, so the message stays readable.

Basic usage

Poll renders without your help in every message that carries a poll. To show one elsewhere, render it with the message and the poll from the client:

import type { LocalMessage } from "stream-chat";
import { Poll, useChatContext } from "stream-chat-react-native";

export const PinnedPoll = ({ message }: { message: LocalMessage }) => {
  const { client } = useChatContext();
  const poll = message.poll_id
    ? client.polls.fromState(message.poll_id)
    : undefined;

  if (!poll) return null;

  return <Poll message={message} poll={poll} />;
};

Render it inside the Channel or Thread of the message.

Poll UI customization

Poll is built from these parts. The ones with an override key are replaced through WithComponents.

The buttons of PollButtons, and when each shows:

In PollResultsContent, an option with more than five votes has ShowAllVotesButton, "Show All", when the user has the query-poll-votes capability. It opens PollOptionFullResults. VoteButton shows while the user has cast-poll-vote and the poll is open; pressing it casts the vote, or removes it when the user already voted for the option.

Replace a part

This PollContent shows three options, and keeps the SDK's header and buttons:

import { StyleSheet, View } from "react-native";
import {
  PollButtons,
  PollHeader,
  PollOption,
  usePollState,
} from "stream-chat-react-native";
import type { ComponentOverrides } from "stream-chat-react-native";

const ThreeOptionPollContent = () => {
  const { options } = usePollState();

  return (
    <View style={styles.container}>
      <PollHeader />
      {options.slice(0, 3).map((option) => (
        <PollOption key={option.id} option={option} />
      ))}
      <PollButtons />
    </View>
  );
};

// Pass to `WithComponents`, declared once at module scope.
export const pollOverrides: ComponentOverrides = {
  PollContent: ThreeOptionPollContent,
};

const styles = StyleSheet.create({
  container: { gap: 12, padding: 12, width: 256 },
});

The header and the buttons here are the exported defaults, so the PollHeader and PollButtons keys don't apply to this poll. Render the keys' components from useComponentsContext() to keep them. Polls replaces the header.

A part of your own that shows who voted handles anonymous polls itself, as usePollState describes.

Props

Poll

PollContent, PollHeader, PollButtons, EndVoteButton and CreatePollContent take no props; they read the poll from PollContext or the form from CreatePollContentContext. PollContentProps is exported and has no members.

PollOption

VoteButton

PollVoteButtonProps is the type of these props.

Buttons

ViewResultsButton, ShowAllOptionsButton, SuggestOptionButton, AddCommentButton, ShowAllCommentsButton and AnswerListAddCommentButton take PollButtonProps:

ShowAllVotesButton takes ShowAllVotesButtonProps:

GenericPollButton is the button they render, for a button of your own. It takes GenericPollButtonProps, every prop of the SDK's Button made optional, with variant "secondary", type "ghost" and size "sm" by default. Its main props are label, onPress, LeadingIcon, TrailingIcon, iconOnly, selected, variant ("primary", "secondary" or "destructive"), type ("solid", "outline" or "ghost"), size ("sm", "md" or "lg"), accessibilityLabelKey and accessibilityLabelParams; see Buttons and inputs.

Poll screens

Each screen takes the message and the poll, provides PollContext with them, and renders its content override. A screen of your own renders them with what a button's onPress received.

The content overrides get the same props without message and poll: additionalScrollViewProps, additionalFlatListProps and, for PollOptionFullResultsContent, option. The additional props are spread onto the ScrollView or FlatList after the SDK's own, so they replace them. PollResultsProps, PollAllOptionsContentProps, PollAnswersListProps and PollOptionFullResultsProps are the screens' prop types. PollVoteClass is PollVoteResponseData from stream-chat.

PollResultsItem renders one option in the results, with option: PollOptionResponseData and its index: number in the sorted list. PollAnswerListItem renders one comment, with answer: PollVoteResponseData; it hides the author of another user's comment in an anonymous poll, and renders AnswerListAddCommentButton under the user's own.

PollModal

PollModal is the React Native Modal the buttons open their screens in. It presents as a page sheet on iOS and draws under the system bars on Android.

PollModalHeader is the header of the screens:

PollInputDialog is the dialog of SuggestOptionButton and AddCommentButton:

CreatePoll

CreatePoll provides CreatePollContentContext and renders the CreatePollContent override, or the default form. MessageComposer renders it in a PollModal while the poll creation dialog is open. When it unmounts, it resets the composer's pollComposer.

The default form has a header with a back button and a send button, the question, the options, which the user can drag to reorder, and switches for multiple votes with a maximum, anonymous voting, suggested options and comments. Each field writes into messageComposer.pollComposer. The SDK exports CreatePollOptions, the list of options, and MultipleVotesSettings, the multiple-votes switch and its maximum, for a form of your own built from them; the question field and the header aren't exported.

PollContext

Poll and the poll screens provide PollContext. usePollContext() reads it, and throws outside one.

PollContext and PollContextProvider, which takes a value of this type, are exported too. The poll's state is in poll.state; Poll hooks lists its fields and what usePollState() returns.

CreatePollContentContext

CreatePoll provides CreatePollContentContext. useCreatePollContentContext() reads it, and throws outside CreatePoll.

A CreatePollContent of your own reads the form's data from useMessageComposer().pollComposer and calls createAndSendPoll() and closePollCreationDialog() from here. Create polls from your own UI replaces the whole sheet instead.

Examples

Show the user's votes

import { Text } from "react-native";
import { usePollState } from "stream-chat-react-native";

export const MyVotes = () => {
  const { options, ownVotesByOptionId } = usePollState();
  const chosen = options.filter((option) => ownVotesByOptionId[option.id]);

  if (!chosen.length) return <Text>You haven't voted yet.</Text>;

  return (
    <Text>You voted for {chosen.map(({ text }) => text).join(", ")}.</Text>
  );
};

Render it inside a poll part, for example in your own PollContent.

Related hooks

See Poll hooks.