\n\n🧩 **kompozr** is a composable UI layer for\n[discord.js](https://discord.js.org/) bots, providing ergonomic wrapper\nfunctions for building Discord UI components with less boilerplate and a focus\non developer experience.\n\n---\n\n## 📚 Table of Contents\n\n- [About](#about)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Components & Usage](#components--usage)\n - [Buttons](#buttons)\n - [Select Menus](#select-menus)\n - [Modals & Inputs](#modals--inputs)\n - [Layout Components](#layout-components)\n - [Content Components](#content-components)\n - [Reactive Components](#️-reactive-components)\n- [Full Example](#full-example)\n- [Full Example With Reactive Components](#full-example-with-reactive-components)\n- [API Reference](#api-reference)\n- [TypeScript Support](#typescript-support)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## ℹ️ About\n\nkompozr was created to **improve the developer experience** when building\nDiscord bots with [discord.js](https://discord.js.org/). \nThe Discord.js builder API is powerful, but can be verbose and repetitive for\ncommon UI patterns. kompozr introduces a philosophy of **\"less builders\"**:\n\n- Compose UIs with fewer lines of code\n- Use simple, declarative wrappers instead of chaining builder methods\n- Focus on what your UI should do, not how to wire up every builder\n\nkompozr is **open source** and welcomes contributions! If you have ideas,\nimprovements, or new components, feel free to open a PR or issue on\n[GitHub](https://github.com/primepvi/kompozr).\n\n---\n\n## ✨ Features\n\n- **Developer Experience First:** Less boilerplate, more readable code, and a\n declarative API.\n- **Composable:** Easily combine components and layouts.\n- **All Discord UI Components:** Buttons, select menus (all types), modals,\n inputs, galleries, files, and more.\n- **Layout Helpers:** Rows, sections, containers, separators, and flexible\n layouts.\n- **Type-safe:** Written in TypeScript with full type definitions.\n- **Less Builders Philosophy:** No more endless `.addX()` and `.setY()`\n chains—just describe your UI in objects and arrays.\n- **Reactive Utilities:** Advanced helpers for stateful, memoized, and reusable\n UI fragments.\n- **Open Source:** Contributions and PRs are welcome!\n\n---\n\n## 🚀 Installation\n\n```sh\nnpm install kompozr\n```\n\n---\n\n## ⚡ Quick Start\n\nImport the main API object:\n\n```ts\nimport { k } from \"kompozr\";\n```\n\n---\n\n## 🛠️ Components & Usage\n\n### Buttons\n\nButtons are interactive components that users can click. With kompozr, you can\neasily create all Discord button styles using a simple and consistent API. Each\nbutton requires a `cid` (custom id) and a `label` or `emoji`. You can also add\nboth and set the button as disabled.\n\n```ts\nconst button = k.button.primary({\n cid: \"my_button\",\n label: \"Click me!\",\n emoji: \"👋\",\n});\n```\n\nOther button styles:\n\n- `k.button.secondary` – Gray button for secondary actions.\n- `k.button.success` – Green button for positive actions.\n- `k.button.danger` – Red button for destructive actions.\n- `k.button.link` – Link button (use `url` instead of `cid`).\n\n#### Example\n\n```ts\nconst linkButton = k.button.link({\n url: \"https://github.com/silentadv/kompozr\",\n label: \"GitHub\",\n});\n```\n\n---\n\n### Select Menus\n\nSelect menus allow users to pick one or more options from a dropdown. kompozr\nsupports all Discord select menu types, including string, role, user, channel,\nand mentionable selects. Each select requires a `cid` and an array of options.\n\n> **Default Values:** \n> For select menus that support default values (user, role, channel,\n> mentionable), use the `defaultValues` property and the helpers:\n>\n> - `k.selectValue.user(id)`\n> - `k.selectValue.role(id)`\n> - `k.selectValue.channel(id)`\n\n```ts\nconst selectMenu = k.select.string({\n cid: \"my_select\",\n options: [\n { value: \"1\", label: \"Option 1\" },\n { value: \"2\", label: \"Option 2\" },\n ],\n placeholder: \"Choose an option\",\n});\n```\n\nOther select types:\n\n- `k.select.role` – Select one or more roles.\n- `k.select.user` – Select one or more users.\n- `k.select.channel` – Select one or more channels.\n- `k.select.mentionable` – Select users or roles.\n\n#### Example: Channel Select\n\n```ts\nconst channelSelect = k.select.channel({\n cid: \"channel_select\",\n placeholder: \"Pick a channel\",\n channelTypes: [ChannelType.GuildText, ChannelType.GuildVoice],\n});\n```\n\n#### Example: User Select with Default Options\n\n```ts\nconst userSelect = k.select.user({\n cid: \"user_select\",\n placeholder: \"Pick a user\",\n defaultValues: [\n k.selectValue.user(\"user-id-1\"),\n k.selectValue.user(\"user-id-2\"),\n ],\n});\n```\n\n---\n\n### Modals & Inputs\n\nModals are pop-up forms that can collect user input. kompozr lets you build\nmodals with short or paragraph text inputs. Each input requires a `cid` and a\n`label`. You can mark inputs as required and set placeholders.\n\n```ts\nconst modal = k.modal({\n cid: \"feedback_modal\",\n title: \"Feedback\",\n inputs: [\n k.input.short({\n cid: \"username\",\n label: \"Your Name\",\n required: true,\n }),\n k.input.paragraph({\n cid: \"feedback\",\n label: \"Your Feedback\",\n required: true,\n }),\n ],\n});\n```\n\n---\n\n### Layout Components\n\nkompozr provides helpers to organize your UI components into rows, sections,\ncontainers, and layouts.\n\n#### Action Row\n\nUse `row` only to group buttons. Discord allows only one select menu per row,\nand kompozr's select wrappers already return a row containing the select menu.\n\n```ts\nconst row = k.row(\n k.button.success({ cid: \"ok\", label: \"OK\" }),\n k.button.danger({ cid: \"cancel\", label: \"Cancel\" })\n);\n```\n\n#### Section\n\nSections let you combine text and an accessory (like a button or select) in a\nsingle block. Use `section` to align text (max 3 text display) side by side with\nan accessory, such as a button or a thumbnail. The main content can be a plain\nstring or a component created with `k.text`. This makes it easy to display a\nmessage with an interactive element or image next to it.\n\n```ts\nconst section = k.section({\n components: [\"Welcome to the server!\", k.text(\"Enjoy your stay!\")],\n accessory: k.button.primary({ cid: \"welcome\", label: \"Say Hi!\" }),\n});\n```\n\n#### Separator\n\nSeparators visually divide content. Choose from different sizes and visibility.\n\n```ts\nk.separator.small; // small spacing\nk.separator.large; // large spacing\nk.separator.smallHidden; // small spacing without divider (only space)\nk.separator.largeHidden; // large spacing without divider (only space)\n```\n\n#### Container\n\nContainers are an layout block for messages, is a component composer, allowing\nyou to group sections, rows, separators, and other components. You can also set\na color for the container.\n\n```ts\nconst container = k.container({\n components: [\n section,\n k.row(\n k.button.success({ cid: \"ok\", label: \"OK\" }),\n k.button.danger({ cid: \"cancel\", label: \"Cancel\" })\n ),\n k.separator.small,\n \"good text here.\",\n k.text(\"line 1\", \"line 2\"),\n ],\n color: \"Blurple\", // or [114,137,218], #ff0000, 0xff\n});\n```\n\n#### Layout (Base)\n\nThe `layout` utility is a simple helper that lets you combine any\ncomponents—including plain strings—into a single array. This means you can use\nstrings directly in your layouts without always needing to wrap them with\n`k.text` or a text display builder. It's mainly for convenience and advanced\ncustom layouts, and does not support color like `container`.\n\n```ts\nconst layout = k.layout(\n k.text(\"Header\"),\n k.row(\n k.button.primary({ cid: \"a\", label: \"A\" }),\n k.button.secondary({ cid: \"b\", label: \"B\" })\n ),\n k.separator.small,\n \"Hello World!\"\n);\n```\n\n---\n\n### Content Components\n\nkompozr also provides helpers for displaying text, images, files, and media\ngalleries.\n\n#### Text Display\n\nDisplay plain or formatted text in your UI.\n\n```ts\nconst text = k.text(\"Hello, world!\");\nconst multiLineText = k.text(\"Line1\", \"Line2\", \"Line3\");\n```\n\n#### Thumbnail\n\nAdd a thumbnail image with an optional description.\n\n```ts\nconst thumbnail = k.thumbnail({\n url: \"https://example.com/thumb.png\",\n description: \"A thumbnail\",\n});\n```\n\n#### File\n\nAttach a file to your message, with optional spoiler support.\n\n```ts\nconst file = k.file({\n url: \"https://example.com/file.pdf\",\n spoiler: true,\n});\n```\n\n#### Media Gallery\n\nDisplay a gallery of images or media files. Each item can have a description and\nbe marked as a spoiler.\n\n```ts\nconst gallery = k.gallery(\n { url: \"https://example.com/image1.png\", description: \"First image\" },\n { url: \"https://example.com/image2.png\", spoiler: true }\n);\n```\n\n---\n\n### Reactive Components\n\nkompozr also provides a set of **reactive utilities** for advanced UI\ncomposition and state management. These are useful for building dynamic,\nstateful, or memoized UI fragments in your Discord bot.\n\n#### When to Use\n\n- When you want to **reuse UI fragments** with different props (like React\n fragments).\n- When you need to **memoize** expensive UI computations and only update when\n dependencies change.\n- When you want to **manage local state** for a UI component or section.\n\n---\n\n#### `k.fragment`\n\nCreates a reusable UI fragment (like a functional component). \nUse when you want to generate repeated or parameterized UI blocks.\n\n**Example:**\n\n```ts\ninterface User {\n id: string;\n username: string;\n}\n\n// type anotation only is necessary in typescript projects.\n// In javascript projects just call k.fragment(...)\n\nconst UserSection = k.fragment((user) =>\n k.section({\n components: [`User: ${user.username}`],\n accessory: k.button.primary({ cid: `user_${user.id}`, label: \"Select\" }),\n })\n);\n\n// Usage:\nconst users = [\n { id: \"1\", username: \"Alice\" },\n { id: \"2\", username: \"Bob\" },\n];\nconst userSections = UserSection(users); // returns an array of sections\n```\n\n**Use case:** \nReusable UI blocks for lists, cards, or repeated sections.\n\n---\n\n#### `k.memo`\n\nMemoizes a UI fragment, only recomputing when dependencies change. \nUse when you have expensive UI generation logic and want to avoid unnecessary\nrecomputation.\n\n**Example:**\n\n```ts\ninterface Props {\n value: number;\n}\n\n// type anotation only is necessary in typescript projects.\n// In javascript projects just use (props) => ... and (props) => [...]\n\nconst ExpensiveSection = k.memo(\n (props: Props) =>\n k.section({\n components: [`Value: ${props.value}`],\n accessory: k.button.primary({ cid: \"btn\", label: \"Go\" }),\n }),\n (props: Props) => [props.value] // dependencies\n);\n\n// Usage:\nconst section = ExpensiveSection({ value: 42 }); // build\n\nExpensiveSection({ value: 42 }); // cached\nExpensiveSection({ value: 44 }); // rebuild because dependencies are changed\nExpensiveSection({ value: 44 }); // cached\nExpensiveSection({ value: 42 }); // rebuild because dependencies are changed\n```\n\n**Use case:** \nPerformance optimization for dynamic UIs that depend on changing props.\n\n---\n\n#### `k.stateful`\n\nCreates a stateful UI component with local state and an update method. \nUse when you want to encapsulate state and rendering logic together.\n\n**Example:**\n\n```ts\nconst counter = k.stateful({ count: 0 }, (state) =>\n k.section({\n components: [`Count: ${state.count}`],\n accessory: k.button.primary({ cid: \"inc\", label: \"Increment\" }),\n })\n);\n\n// Usage:\ncounter.render(); // renders with current state\ncounter.update({ count: counter.state.count + 1 }); // update state\n```\n\n**Use case:** \nLocal state management for interactive or dynamic UI sections.\n\n---\n\n## Full Example\n\n```ts\nimport { k } from \"kompozr\";\n\nconst button = k.button.success({\n cid: \"ok_btn\",\n label: \"OK\",\n});\n\nconst gallery = k.gallery({\n url: \"https://example.com/cat.png\",\n description: \"A cute cat\",\n});\n\nconst message = k.container({\n components: [\n k.section({\n components: [\"Check out this gallery!\"],\n acessory: button,\n }),\n gallery,\n k.separator.small,\n k.text(\"Thanks for using kompozr!\"),\n ],\n color: \"Green\",\n});\n\n// Send `message` as your bot's response\n```\n\n---\n\n## Full Example with Reactive Components\n\n```ts\nconst UserCard = k.fragment((user) =>\n k.section({\n components: [`👤 ${user.name}`],\n accessory: k.button.primary({ cid: `select_${user.id}`, label: \"Select\" }),\n })\n);\n\nconst userList: User[] = [\n { id: \"1\", name: \"Alice\" },\n { id: \"2\", name: \"Bob\" },\n];\n\nconst message = k.container({\n components: [\n ...UserCard(userList), // list of sections\n k.separator.small,\n k.text(\"Select a user!\"),\n ],\n});\n```\n\n---\n\n## API Reference\n\nAll builder functions return Discord.js builder instances, ready to be used in\nyour bot's responses.\n\n- **Buttons:** `k.button.primary`, `k.button.secondary`, `k.button.success`,\n `k.button.danger`, `k.button.link`\n- **Select Menus:** `k.select.string`, `k.select.role`, `k.select.user`,\n `k.select.channel`, `k.select.mentionable`\n- **Populated Select Menus Values:** `k.selectValue.user`, `k.selectValue.role`,\n `k.selectValue.channel`\n- **Modals & Inputs:** `k.modal`, `k.input.short`, `k.input.paragraph`\n- **Layout:** `k.row`, `k.section`, `k.container`, `k.separator`, `k.layout`\n- **Content:** `k.text`, `k.thumbnail`, `k.gallery`, `k.file`\n- **Reactive:** `k.memo`, `k.stateful`, `k.fragment`\n\n---\n\n## TypeScript Support\n\nkompozr is written in TypeScript and ships with full type definitions.\n\n---\n\n## Contributing\n\nkompozr is **open source** and contributions are welcome! \nIf you have suggestions, bug reports, or want to add new features/components,\nplease open an issue or PR on [GitHub](https://github.com/primepvi/kompozr).\n\n---\n\n## License\n\nMIT\n\n---\n\n> Made with ❤️ by [primepvi](https://github.com/primepvi)\n","readmeFilename":"README.md"}
![\"kompozr](\"https://raw.githubusercontent.com/primepvi/kompozr/main/assets/kompozr.png\")
\n![\"npm](\"https://img.shields.io/npm/v/kompozr.svg?style=flat-square\")
\n \n \n ![\"npm](\"https://img.shields.io/npm/dm/kompozr.svg?style=flat-square\")
\n \n \n ![\"GitHub](\"https://img.shields.io/github/stars/primepvi/kompozr?style=flat-square\")
![\"License:](\"https://img.shields.io/badge/License-MIT-green.svg?style=flat-square\"){kind=icon}
\n \n