@gram-ai/elements 1.2.3 → 1.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +201 -0
  2. package/dist/types/index.d.ts +4 -0
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -77,6 +77,207 @@ export const App = () => {
77
77
  }
78
78
  ```
79
79
 
80
+ ## Configuration
81
+
82
+ The `ElementsConfig` object accepts the following configuration options:
83
+
84
+ ### Top-Level Configuration
85
+
86
+ | Property | Type | Required | Status | Default | Description |
87
+ | -------------- | ---------------------------------------------------------- | -------- | ---------------------- | --------------------- | --------------------------------------------------------------------------------------------------- |
88
+ | `projectSlug` | `string` | Yes | ✅ Implemented | - | The project slug to use for the Elements library |
89
+ | `mcp` | `string` | Yes | ✅ Implemented | - | The Gram Server URL. Can be retrieved from `https://app.getgram.ai/{team}/{project}/mcp/{mcp_slug}` |
90
+ | `chatEndpoint` | `string` | No | ✅ Implemented | `'/chat/completions'` | The path of your backend's chat endpoint |
91
+ | `environment` | `Record<string, unknown>` | No | ⚠️ Not yet functional | `undefined` | Custom environment variable overrides for the MCP server |
92
+ | `variant` | `'widget' \| 'standalone'` | No | ✅ Implemented | `undefined` | Whether to render the chat window inside an expandable modal or as a standalone chat window |
93
+ | `theme` | `'light' \| 'dark' \| 'system'` | No | ⚠️ Not yet implemented | `undefined` | The theme to use for the Elements library |
94
+ | `welcome` | [`WelcomeConfig`](#welcome-configuration-welcomeconfig) | Yes | ✅ Implemented | - | Configuration for the welcome message and initial suggestions |
95
+ | `composer` | [`ComposerConfig`](#composer-configuration-composerconfig) | No | ✅ Implemented | `undefined` | Configuration for the composer input |
96
+ | `modal` | [`ModalConfig`](#modal-configuration-modalconfig) | No | ✅ Implemented | `undefined` | Configuration for the modal window (only applies when `variant` is `'widget'`) |
97
+ | `model` | [`ModelConfig`](#model-configuration-modelconfig) | No | ✅ Implemented | `undefined` | LLM model configuration |
98
+ | `tools` | [`ToolsConfig`](#tools-configuration-toolsconfig) | No | ✅ Implemented | `undefined` | Configuration for custom tool components |
99
+
100
+ ### Welcome Configuration (`WelcomeConfig`)
101
+
102
+ | Property | Type | Required | Status | Default | Description |
103
+ | ------------- | ------------------------------------ | -------- | -------------- | ----------- | --------------------------------------------------------------- |
104
+ | `title` | `string` | Yes | ✅ Implemented | - | The welcome message title to display when the thread is empty |
105
+ | `subtitle` | `string` | Yes | ✅ Implemented | - | The subtitle to display when the thread is empty |
106
+ | `suggestions` | [`Suggestion[]`](#suggestion-object) | No | ✅ Implemented | `undefined` | Array of suggestion prompts to display when the thread is empty |
107
+
108
+ #### Suggestion Object
109
+
110
+ | Property | Type | Required | Status | Description |
111
+ | -------- | -------- | -------- | -------------- | ---------------------------------------------- |
112
+ | `title` | `string` | Yes | ✅ Implemented | The title of the suggestion |
113
+ | `label` | `string` | Yes | ✅ Implemented | The label text for the suggestion |
114
+ | `action` | `string` | Yes | ✅ Implemented | The prompt text that will be sent when clicked |
115
+
116
+ ### Composer Configuration (`ComposerConfig`)
117
+
118
+ | Property | Type | Required | Status | Default | Description |
119
+ | ------------- | --------- | -------- | ---------------------- | ------- | --------------------------------------------- |
120
+ | `placeholder` | `string` | Yes | ✅ Implemented | - | The placeholder text for the composer input |
121
+ | `attachments` | `boolean` | Yes | ⚠️ Not yet implemented | - | Whether to enable attachments in the composer |
122
+
123
+ ### Modal Configuration (`ModalConfig`)
124
+
125
+ | Property | Type | Required | Status | Default | Description |
126
+ | ------------- | ------------------------------------------------------- | -------- | -------------- | ----------- | ------------------------------------------------------------ |
127
+ | `defaultOpen` | `boolean` | No | ✅ Implemented | `false` | Whether to open the modal window by default |
128
+ | `icon` | `(state: 'open' \| 'closed' \| undefined) => ReactNode` | No | ✅ Implemented | `undefined` | Custom icon component function that receives the modal state |
129
+ | `className` | `string` | No | ✅ Implemented | `undefined` | Additional CSS class name to apply to the modal window |
130
+
131
+ ### Model Configuration (`ModelConfig`)
132
+
133
+ | Property | Type | Required | Status | Default | Description |
134
+ | ----------------- | ---------------------------- | -------- | -------------- | ------------------------------- | ------------------------------------------------ |
135
+ | `showModelPicker` | `boolean` | No | ✅ Implemented | `false` | Whether to show the model picker in the composer |
136
+ | `defaultModel` | [`Model`](#available-models) | No | ✅ Implemented | `'anthropic/claude-sonnet-4.5'` | The default model to use |
137
+
138
+ #### Available Models
139
+
140
+ The following models are currently supported:
141
+
142
+ - `anthropic/claude-sonnet-4.5`
143
+ - `anthropic/claude-haiku-4.5`
144
+ - `anthropic/claude-sonnet-4`
145
+ - `anthropic/claude-opus-4.5`
146
+ - `openai/gpt-4o`
147
+ - `openai/gpt-4o-mini`
148
+ - `openai/gpt-5.1-codex`
149
+ - `openai/gpt-5`
150
+ - `openai/gpt-5.1`
151
+ - `openai/gpt-4.1`
152
+ - `anthropic/claude-3.7-sonnet`
153
+ - `anthropic/claude-opus-4`
154
+ - `google/gemini-2.5-pro-preview`
155
+ - `google/gemini-3-pro-preview`
156
+ - `moonshotai/kimi-k2`
157
+ - `mistralai/mistral-medium-3`
158
+ - `mistralai/mistral-medium-3.1`
159
+ - `mistralai/codestral-2501`
160
+
161
+ ### Tools Configuration (`ToolsConfig`)
162
+
163
+ | Property | Type | Required | Status | Default | Description |
164
+ | ------------ | ---------------------------------------------- | -------- | -------------- | ----------- | ------------------------------------------------------------------------------------------ |
165
+ | `components` | `Record<string, ToolCallMessagePartComponent>` | No | ✅ Implemented | `undefined` | Override default React components for specific tool results. Tool names must match exactly |
166
+
167
+ ### Configuration Examples
168
+
169
+ #### Minimal Configuration
170
+
171
+ ```typescript
172
+ import { ElementsConfig } from '@gram-ai/elements'
173
+
174
+ const config: ElementsConfig = {
175
+ projectSlug: 'my-project',
176
+ mcp: 'https://app.getgram.ai/mcp/my-mcp-slug',
177
+ welcome: {
178
+ title: 'Welcome!',
179
+ subtitle: 'How can I assist you today?',
180
+ },
181
+ }
182
+ ```
183
+
184
+ #### Full Configuration with All Options
185
+
186
+ ```typescript
187
+ import { ElementsConfig } from '@gram-ai/elements'
188
+ import { WeatherComponent } from './components/WeatherComponent'
189
+
190
+ const config: ElementsConfig = {
191
+ projectSlug: 'my-project',
192
+ mcp: 'https://app.getgram.ai/mcp/my-mcp-slug',
193
+ chatEndpoint: '/api/chat',
194
+ variant: 'widget',
195
+ theme: 'system',
196
+ environment: {
197
+ API_KEY: 'your-api-key',
198
+ BASE_URL: 'https://api.example.com',
199
+ },
200
+ welcome: {
201
+ title: 'Hello!',
202
+ subtitle: 'How can I help you today?',
203
+ suggestions: [
204
+ {
205
+ title: 'Get Weather',
206
+ label: 'Check current weather',
207
+ action: 'What is the weather like today?',
208
+ },
209
+ {
210
+ title: 'Summarize',
211
+ label: 'Summarize a document',
212
+ action: 'Can you summarize this document for me?',
213
+ },
214
+ ],
215
+ },
216
+ composer: {
217
+ placeholder: 'Type your message...',
218
+ attachments: true,
219
+ },
220
+ modal: {
221
+ defaultOpen: false,
222
+ className: 'custom-modal-class',
223
+ },
224
+ model: {
225
+ showModelPicker: true,
226
+ defaultModel: 'anthropic/claude-sonnet-4.5',
227
+ },
228
+ tools: {
229
+ components: {
230
+ get_current_weather: WeatherComponent,
231
+ },
232
+ },
233
+ }
234
+ ```
235
+
236
+ #### Widget Variant with Custom Modal Icon
237
+
238
+ ```typescript
239
+ import { ElementsConfig } from '@gram-ai/elements'
240
+ import { MessageSquare, X } from 'lucide-react'
241
+
242
+ const config: ElementsConfig = {
243
+ projectSlug: 'my-project',
244
+ mcp: 'https://app.getgram.ai/mcp/my-mcp-slug',
245
+ variant: 'widget',
246
+ welcome: {
247
+ title: 'Chat with us!',
248
+ subtitle: 'Ask anything',
249
+ },
250
+ modal: {
251
+ defaultOpen: true,
252
+ icon: (state) => (state === 'open' ? <X /> : <MessageSquare />),
253
+ },
254
+ }
255
+ ```
256
+
257
+ #### Standalone Variant with Model Picker
258
+
259
+ ```typescript
260
+ import { ElementsConfig } from '@gram-ai/elements'
261
+
262
+ const config: ElementsConfig = {
263
+ projectSlug: 'my-project',
264
+ mcp: 'https://app.getgram.ai/mcp/my-mcp-slug',
265
+ variant: 'standalone',
266
+ welcome: {
267
+ title: 'AI Assistant',
268
+ subtitle: 'Choose a model and start chatting',
269
+ },
270
+ composer: {
271
+ placeholder: 'Ask me anything...',
272
+ attachments: true,
273
+ },
274
+ model: {
275
+ showModelPicker: true,
276
+ defaultModel: 'openai/gpt-4o',
277
+ },
278
+ }
279
+ ```
280
+
80
281
  ## Contributing
81
282
 
82
283
  We welcome pull requests to Elements. Please read the contributing guide.
package/dist/types/index.d.ts CHANGED
@@ -38,6 +38,8 @@ export interface ElementsConfig {
38
38
  /**
39
39
  * Custom environment variable overrides for the Elements library.
40
40
  * Will be used to override the environment variables for the MCP server.
41
+ *
42
+ * TODO: Not yet functional
41
43
  */
42
44
  environment?: Record<string, unknown>;
43
45
  /**
@@ -58,6 +60,8 @@ export interface ElementsConfig {
58
60
  model?: ModelConfig;
59
61
  /**
60
62
  * The theme to use for the Elements library.
63
+ *
64
+ * TODO: Not yet implemented
61
65
  */
62
66
  theme?: 'light' | 'dark' | 'system';
63
67
  /**
package/package.json CHANGED
@@ -2,7 +2,7 @@
2
2
  "name": "@gram-ai/elements",
3
3
  "description": "Gram Elements is a library of UI primitives for building chat-like experiences for MCP Servers.",
4
4
  "type": "module",
5
- "version": "1.2.3",
5
+ "version": "1.2.4",
6
6
  "main": "dist/index.js",
7
7
  "exports": {
8
8
  ".": {