Polls

A poll is a question with options that the channel's members vote on. It's created on the server first, and then its id is attached to the sent message. While the user fills in the poll form, the poll composer, messageComposer.pollComposer, holds the form and checks each field.

What it holds

The poll composer's state is in pollComposer.state. It has two fields: data (stores the form's state), and errors, the problems found in it.

data holds the poll's fields:

Each field has a getter that reads its current value, such as pollComposer.name or pollComposer.options. pollComposer.canCreatePoll says whether the form is complete: the question is set, at least one option has text, max_votes_allowed is empty or a number from 2 to 10, and pollComposer.state.errors holds no validation error.

Filling in the form

Each change passes the form through the poll middleware: a pipeline of functions that processes the changed fields and checks them, as Composer middleware explains.

What a poll form needs, and the call for each (the last column says which middleware handler a call runs):

The SDK's creation sheet calls PollComposer.updateFields() as the user types, PollComposer.handleFieldBlur() when the user leaves the question, an option or the maximum number of votes, and PollComposer.initState() when it closes.

const { pollComposer } = channel.messageComposer;

await pollComposer.updateFields({ data: { name: "Lunch?" } });
await pollComposer.updateFields({
  data: { options: { index: 0, text: "Pizza" } },
});

While processing a change, the built-in middleware keeps the form consistent: changing enforce_unique_vote empties max_votes_allowed, and max_votes_allowed is turned into a whole number from 2 to 10, or '' when it isn't a number.

PollComposer.updateFields() also takes injectedFieldErrors, errors of your own, for example from a check performed by your own logic. They win over the errors the middleware finds.

For example, to reject questions that your own check doesn't allow:

import type { MessageComposer, PollComposerValidationCode } from "stream-chat";

// Your own check, for example a request to your server.
const isQuestionAllowed = async (name: string) => !name.includes("spam");

const changeQuestion = async (composer: MessageComposer, name: string) => {
  const allowed = await isQuestionAllowed(name);

  await composer.pollComposer.updateFields({
    data: { name },
    injectedFieldErrors: {
      name: allowed
        ? undefined
        : {
            // `code` takes only the built-in codes, so a code of your own needs a cast.
            code: "myapp:poll:name:notAllowed" as PollComposerValidationCode,
            message: "This question isn't allowed",
          },
    },
  });
};

The error is saved to pollComposer.state.errors.name, and pollComposer.canCreatePoll stays false while it's there. Passing undefined for a field clears your error.

Validation errors

While the user fills in the form, the poll composer saves field errors in pollComposer.state.errors, for your UI to show next to the fields. While any error is there, pollComposer.canCreatePoll is false.

Subscribe to pollComposer.state to show the errors as they change:

const { pollComposer } = channel.messageComposer;

const unsubscribe = pollComposer.state.subscribeWithSelector(
  ({ errors }) => ({ errors }),
  ({ errors }) => {
    // The question's error, or undefined when the question is fine.
    if (errors.name) {
      console.log(errors.name.code, errors.name.message);
    }

    // One error per option that has a problem, keyed by the option's id.
    Object.entries(errors.options ?? {}).forEach(([optionId, error]) => {
      console.log(optionId, error.code, error.message);
    });
  },
);

For example, after the user leaves the question empty and types "Pizza" into two options, pollComposer.state.errors is:

{
  "name": {
    "code": "validation:poll:name:required",
    "message": "Question is required"
  },
  "options": {
    "<id of the second Pizza option>": {
      "code": "validation:poll:option:duplicate",
      "message": "Option already exists"
    }
  }
}

code says what's wrong: translate it. message is in English, to show when you have no translation.

The table lists every code, and where to read it:

The built-in processing already turns max_votes_allowed into a number from 2 to 10, so the last two appear only with processors of your own.

The SDK's creation sheet shows an option's error under the option. For the built-in optionDuplicate and optionEmpty codes it shows its own translated text, and for any other code the error's message. It shows no text for an error of the question or of max_votes_allowed. Any error disables the send button, because PollComposer.canCreatePoll is false while an error is set.

Validators and processors

PollComposer.updateFields() runs handleFieldChange on the poll state chain, with the fields it changes. PollComposer.handleFieldBlur(field) runs handleFieldBlur with one field.

For each field in the change, the built-in middleware runs the field's processor, then the field's validator:

• A processor receives { data, value } and returns the fields to store, such as { name: value.trim() }. It can return more than one field.
• A validator receives { data, value, currentError } and returns errors by field. { name: undefined } clears the question's error. It can set or clear the errors of other fields too.

data is the poll before the change, value is the field's new value after its processor, and currentError is the field's error before the change. The built-in functions are exported:

createPollComposerStateMiddleware({ processors, validators }) takes your functions by event, then by field, as in { handleFieldBlur: { name: validateName } }. Each one replaces the built-in function for the same field and event, and the other built-in functions keep running. To keep a built-in check, call the built-in function from yours. A processor of your own for options replaces the one that removes and adds options. Its value is the whole list when the options are reordered, and { index, text } when one option changes. isTargetedOptionTextUpdate(value) tells them apart.

An error is a PollComposerValidationError, { code, message, metadata? }. stream-chat builds its own with pollComposerValidationError(code), and the type of code allows only the codes in POLL_COMPOSER_VALIDATION_CODE. For a check of your own, give the error a code of your own, cast to PollComposerValidationCode, and the text to show as message. A prefix such as my-app: keeps your codes apart from the built-in ones.

This setup limits each option to 40 characters, and keeps the built-in checks for duplicate and empty options:

import {
  createPollComposerStateMiddleware,
  defaultPollFieldBlurEventValidators,
  pollStateChangeValidators,
  StreamChat,
} from "stream-chat";
import type {
  PollComposerOption,
  PollComposerValidationCode,
  PollComposerValidationError,
  PollStateChangeValidator,
} from "stream-chat";

const client = StreamChat.getInstance("YOUR_API_KEY");

const MAX_OPTION_LENGTH = 40;

// The type of `code` allows only the built-in codes, so a code of your own is cast.
const ownError = (
  code: string,
  message: string,
): PollComposerValidationError => ({
  code: code as PollComposerValidationCode,
  message,
});

const withLengthCheck =
  (builtIn: PollStateChangeValidator | undefined): PollStateChangeValidator =>
  (params) => {
    const errors = { ...builtIn?.(params).options };
    const options: PollComposerOption[] = params.value;

    options.forEach((option) => {
      if (!errors[option.id] && option.text.length > MAX_OPTION_LENGTH) {
        errors[option.id] = ownError(
          "my-app:poll:option:tooLong",
          `Use at most ${MAX_OPTION_LENGTH} characters`,
        );
      }
    });

    return { options: Object.keys(errors).length > 0 ? errors : undefined };
  };

client.config.setSetupFunction("messageComposer", ({ composer }) => {
  const { stateMiddlewareExecutor } = composer.pollComposer;

  stateMiddlewareExecutor.replace([
    createPollComposerStateMiddleware({
      validators: {
        handleFieldChange: {
          options: withLengthCheck(pollStateChangeValidators.options),
        },
        handleFieldBlur: {
          options: withLengthCheck(defaultPollFieldBlurEventValidators.options),
        },
      },
    }),
  ]);

  return () =>
    stateMiddlewareExecutor.replace([createPollComposerStateMiddleware()]);
});

MiddlewareExecutor.replace() puts the new middleware in the place of the built-in one, because both have the same id, and the teardown puts a default one back.

Creating and sending the poll

Creating the poll takes two steps:

const composer = channel.messageComposer;

await composer.createPoll(); // creates the poll on the server and sets composer.pollId
await composer.send(); // sends the message that carries the poll

MessageComposer.createPoll() does nothing while pollComposer.canCreatePoll is false. Otherwise it sends the form, without its empty options, to the server and stores the new poll's id in messageComposer.pollId. When the request fails, it publishes an api:poll:create:failed notification and throws.

While messageComposer.pollId is set, the composer has something to send. In a channel composer, MessageComposer.send() then sends a message that carries only the poll: no text, attachments, mentions, quoted message or custom data. The text, attachments and quoted message stay in the composer, ready to send as the next message, as Messages with a poll explains. After the send, messageComposer.pollId is cleared.

In a thread composer, and while a message is edited, the poll is sent with the rest of the message, and the composer clears after the send.

To send the poll together with the text and attachments in a channel too, remove the poll-only middleware. Its id is exported from stream-chat as POLL_ONLY_COMPOSITION_MIDDLEWARE_ID:

import { POLL_ONLY_COMPOSITION_MIDDLEWARE_ID, StreamChat } from "stream-chat";

const client = StreamChat.getInstance("YOUR_API_KEY");

client.config.setSetupFunction("messageComposer", ({ composer }) => {
  // A poll then goes out with the text and attachments, and the composer clears after the send.
  composer.compositionMiddlewareExecutor.remove(
    POLL_ONLY_COMPOSITION_MIDDLEWARE_ID,
  );
});

A draft keeps messageComposer.pollId, so a poll that was created but not sent comes back with the draft. The form in pollComposer.state isn't saved in it.

When polls are on

Polls are on while messageComposer.config.polls.enabled is true. That's when both the polls.enabled setting in client.config and the channel type's polls setting are on. The composer doesn't check it when it creates or sends a poll: the UI reads it to decide whether to offer polls. Channel reads it to set hasCreatePoll, and the SDK's attachment picker offers polls only outside threads, when hasCreatePoll is true and the user has the send-poll capability.

Settings

Set them for every composer in client.config, under messageComposer.polls:

client.config.set({
  messageComposer: {
    polls: { enabled: false },
  },
});

The poll composer has no setters. To change a setting for one composer only, patch that composer's configuration, for example channel.messageComposer.updateConfig({ polls: { enabled: false } }).

See Polls for the feature, including voting, and the custom poll flow UI cookbook for a creation screen of your own.

Used in

• Polls