snapshot of https://github.com/zulip/zulip.git @ 48c69911c7dd4e03b20552eb3bd77ad8151c1357 (2026-09-15)

docs/subsystems/input-pills.md

@@ -0,0 +1,77 @@
+# UI: input pills
+
+This is a high level and API explanation of the input pill interface in the
+frontend of the Zulip web application.
+
+## Setup
+
+A pill container should have the following markup:
+
+```html
+<div class="pill-container">
+    <div class="input" contenteditable="true"></div>
+</div>
+```
+
+The pills will automatically be inserted in before the ".input" in order.
+
+## Basic usage
+
+```js
+var $pill_container = $("#input_container");
+var pills = input_pill.create({
+    $container: $pill_container,
+    create_item_from_text: user_pill.create_item_from_email,
+    get_text_from_item: user_pill.get_email_from_item,
+    get_display_value_from_item: user_pill.get_display_value_from_item,
+});
+```
+
+You can look at `web/src/user_pill.ts` to see how the above
+methods are implemented. Essentially you just need to convert
+from raw data (like an email) to structured data (like an object
+with display_value, email, and user_id for a user), and vice
+versa.
+
+## Typeahead
+
+Pills almost always work in conjunction with typeahead, and
+you will want to provide a `source` function to typeahead
+that can exclude items from the prior pills. Here is an
+example snippet from our user group settings code.
+
+```js
+source: function () {
+    return user_pill.typeahead_source(pills);
+},
+```
+
+And then in `user_pill.ts`...
+
+```js
+export function typeahead_source(pill_widget) {
+    const persons = people.get_realm_users();
+    return filter_taken_users(persons, pill_widget);
+}
+
+export function filter_taken_users(items, pill_widget) {
+    const taken_user_ids = get_user_ids(pill_widget);
+    items = items.filter((item) => !taken_user_ids.includes(item.user_id));
+    return items;
+}
+```
+
+### `onPillCreate` and `onPillRemove` methods
+
+You can get notifications from the pill code that pills have been
+created/remove.
+
+```js
+pills.onPillCreate(function () {
+    update_save_state();
+});
+
+pills.onPillRemove(function () {
+    update_save_state();
+});
+```