> For the complete documentation index, see [llms.txt](https://seanime.gitbook.io/seanime-extensions/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://seanime.gitbook.io/seanime-extensions/plugins/ui/user-interface/tray.md).
# Tray
Example
## Create a tray icon
{% hint style="info" %}
You can only create one tray icon in your plugin
{% endhint %}
```typescript
const tray = ctx.newTray({
tooltipText: "My plugin",
iconUrl: "https://seanime.rahim.app/logo_2.png",
withContent: true,
isDrawer: false, // Choose whether the tray contents are displayed in a drawer
})
```
## Add a badge
```typescript
tray.updateBadge({ number: 1, intent: "alert" })
// Remove the badge
tray.updateBadge({ number: 0 })
```
* `intent`: "alert" | "info" | "warning" | "success"
## Rendering content
{% hint style="info" %}
`withContent` should be set to 'true'.
{% endhint %}
The `state` is a mechanism to keep track of variable data over time, enabling components to re-render automatically when the data changes.
The `render()` function is used to define how content should be presented in the tray popover. It takes a callback function that returns a tree of components.
Components, like `tray.text` and `tray.button`, are reusable building blocks of the UI, each responsible for rendering a piece of the interface according to the current state.
The tray will be re-rendered anytime there is a state change even if the state isn't in the render function.
const count = ctx.state(0);
ctx.setInterval(() => {
count.set(c => c + 1);
}, 1000);
tray.render(() => {
return tray.stack({
items: [
tray.text(`Count: ${count.get()}`),
// Show the button when the count reaches 5
count.get() >= 5
? tray.button("Click me", { onClick: "button-clicked" })
: trat.text("Nothing here")
],
})
})
## Tray events
```typescript
tray.onOpen(() => {
// User opened the tray content
})
tray.onClose(() => {
// User closed the tray content
})
tray.onClick(() => {
// User clicked the tray icon
})
// Open the tray
// This will not work on the first page load or if the plugin is not pinned
tray.open()
// Close the tray
tray.close()
// Force the tray content to update
// Not useful is most cases because the tray updates when states change
tray.update()
```
## Event handlers
You can register functions to specific event triggers like `onClick` using `ctx.registerEventHandler()` in order to define custom behaviors based on user action.
#### Tips
You can register inline event handlers. Make sure the first argument is unique to that element.
```typescript
tray.stack(allItems.map((item) => {
return tray.flex([
tray.text(key),
tray.button({
label: "Open",
size: "sm",
// It takes a unique ID key as first argument!
onClick: ctx.eventHandler(item.id, () => {
// Do something...
}),
intent: "gray-subtle"
}),
], { gap: 1, style: { alignItems: "center" } })
}))
```
## Base components
```typescript
tray.div([], { style: {} })
tray.stack([], { style: {} })
tray.flex([], { style: {} })
tray.text(...)
tray.anchor(...)
tray.a(...)
tray.p(...)
tray.span(...)
tray.css(...)
tray.badge(...)
tray.alert(...)
tray.img(...)
```
## Fields/Forms
Field components:
* input
* button
* select
* radioGroup
* checkbox
* switch
Use `ctx.fieldRef` to get and set a field's value synchronously.
const textInputRef = ctx.fieldRef<string>("Default value")
// When the form is submitted
ctx.registerEventHandler("submit-form", () => {
// We can get the value of the text input
console.log(textInputRef.current)
// We can change the value of the text input
textInputRef.setValue("")
})
tray.render(() => tray.stack([
text.input("A text field", { fieldRef: textInputRef }),
tray.button("Submit", { onClick: "submit-form" }),
]))