YurbaUI — Documentation

YurbaUI.Modal

Floating overlay dialog window. Supports multiple sizes, placements, footer actions, header controls, auto-close, and declarative attribute binding.

Constructor

const modal = new YurbaUI.Modal(options?)

Option	Type	Default	Description
`size` optional	string	`'default'`	Initial window size. See `setSize()` for allowed values.
`parent` optional	HTMLElement	`document.body`	DOM element the modal is appended to.
`components` optional	array	`null`	Array of components to render. Format: `{ content: Component, area: 'header'\|'body'\|'footer'\|'controls' }`
`closeOnOutsideClick` optional	boolean	`true`	Close modal when clicking outside of it.
`onClose` optional	function	`null`	Called when the user dismisses the modal (close button or outside click).

Methods

Method	Params	Returns	Description
`renderComponent(component, placement?)`	`component` — BaseComponent \| HTMLElement `placement` — `'body'` \| `'header'` \| `'footer'` \| `'controls'`	HTMLElement	Renders a component into the specified placement (defaults to `'body'`). It is recorded and replayed every time the modal reopens.
`show()`	—	void	Shows the modal.
`hide()`	—	void	Hides the modal; it is removed from the DOM after the close animation and rebuilt from its recorded components on the next `show()`.
`remove()`	—	void	Removes the modal from the DOM entirely.
`bind(name)`	`name` — string	void	Binds the modal to all elements with `y-win="name"`. Clicking them opens the modal.
`setSize(size)`	`size` — `'nano'` \| `'small'` \| `'default'` \| `'medium'` \| `'large'` \| `'giant'` \| `'full'`	void	Changes the modal size at any time.
`setPosition(pos)`	`pos` — string	void	Sets modal position class. Used by `YurbaUI.Toast` for corner positioning.
`hideOnTimeout(ms, opts?)`	`ms` — number	void	Auto-hides the modal after `ms` milliseconds from the moment it is shown.
`isShowed()`	—	boolean	Returns `true` if the modal is currently visible.

Element properties

Property	Type	Description
`modal.modalBody`	HTMLElement	Main content area (available only while shown). Prefer the `components` option or `renderComponent()` so content is restored when the modal reopens.
`modal.modalHeader`	HTMLElement	Header area (above the body).
`modal.modalFooterBody`	HTMLElement	Footer action bar (below the body).
`modal.modalControls`	HTMLElement	Top-right controls slot (for icon buttons next to close).
`modal.modalClose`	HTMLElement	The built-in close button element.

Demo

Basic modal

const modal = new YurbaUI.Modal({
    components: [
        { content: new YurbaUI.Title('Hello World'), area: 'header' },
        { content: new YurbaUI.Description('A simple modal window'), area: 'body' },
        { content: new YurbaUI.Text('Body text with <b>HTML</b> support.'), area: 'body' }
    ]
})
modal.show()

With footer button

const closeBtn = new YurbaUI.IconButton(
    { icon: '<span class="material-symbols-rounded">close</span>', name: 'Dismiss' },
    () => modal.hide()
)

const modal = new YurbaUI.Modal({
    components: [
        { content: new YurbaUI.Title('With footer'), area: 'header' },
        { content: new YurbaUI.Text('This modal has an action bar at the bottom.'), area: 'body' },
        { content: closeBtn, area: 'footer' }
    ]
})
modal.show()

Persist on outside click

const modal = new YurbaUI.Modal({
    closeOnOutsideClick: false,
    components: [
        { content: new YurbaUI.Title('Persists when clicking outside'), area: 'header' },
        { content: new YurbaUI.Text('This modal will NOT close when you click outside.'), area: 'body' }
    ]
})
modal.show()

Sizes — setSize(size)

const modal = new YurbaUI.Modal()
// nano | small | default | medium | large | giant | full
modal.setSize('large')
modal.show()

Attribute binding — bind(name)

const modal = new YurbaUI.Modal({
    components: [
        { content: new YurbaUI.Title('Bound modal'), area: 'header' },
        { content: new YurbaUI.Text('Opened via y-win attribute.'), area: 'body' }
    ]
})
modal.bind('bound-modal')

<button y-win="my-modal">Open</button>

YurbaUI.Toast

Factory function that creates a notification toast positioned anywhere on screen. Returns a Modal instance — call .setPosition() and .show() on it.

Usage

const toast = YurbaUI.Toast(props)
toast.setPosition(position)
toast.show()

Note: YurbaUI.Toast is a function, not a constructor — do not use new.

Props

Prop	Type	Required	Description
`title`	string	required	Notification text displayed in the toast.
`icon`	string	optional	Raw HTML icon string, e.g. `'<span class="material-symbols-rounded">check</span>'`.
`iconType`	string	optional	Colors the icon area. Values: `'success'` \| `'danger'` \| `'warn'` \| `'info'`.
`timeout`	number	optional	Auto-close delay in milliseconds after the toast appears.

setPosition(pos) — available positions

Value	Placement
`'top-left'`	Top-left corner
`'top-right'`	Top-right corner
`'top-center'`	Top center
`'bottom-left'`	Bottom-left corner
`'bottom-right'`	Bottom-right corner
`'bottom-center'`	Bottom center

Demo

Default

const t = YurbaUI.Toast({ title: 'Notification' })
t.setPosition('top-right')
t.show()

Success

const t = YurbaUI.Toast({
    title: 'Saved successfully',
    icon: '<span class="material-symbols-rounded">check</span>',
    iconType: 'success'
})
t.setPosition('top-right')
t.show()

Danger

const t = YurbaUI.Toast({
    title: 'Something went wrong',
    icon: '<span class="material-symbols-rounded">exclamation</span>',
    iconType: 'danger'
})
t.setPosition('top-right')
t.show()

Warning

const t = YurbaUI.Toast({
    title: 'Check your input',
    icon: '<span class="material-symbols-rounded">exclamation</span>',
    iconType: 'warn'
})
t.setPosition('top-right')
t.show()

YurbaUI.Tooltip

Attaches a hoverable popover to any DOM element. Automatically repositions itself when near screen edges.

Constructor

new YurbaUI.Tooltip(element, options)

Option	Type	Default	Description
`pos` optional	string	`'top'`	Preferred position: `'top'` \| `'bottom'` \| `'left'` \| `'right'`. Flipped automatically if near an edge.
`title` optional	string	—	Tooltip title text shown in the header.
`content` optional	string	—	Tooltip body text.
`icon` optional	string	—	Raw HTML icon string placed in the tooltip header.
`className` optional	string	—	CSS class added to the tooltip header element (e.g. `'popover-info'`, `'popover-danger'`).
`delay` optional	number	—	Delay in milliseconds before the tooltip appears on hover.
`offset` optional	number	—	Distance in pixels between the target element and the tooltip.

Methods

Method	Params	Returns	Description
`show()`	—	void	Force-shows the tooltip programmatically.
`hide()`	—	void	Force-hides the tooltip programmatically.

Demo

Positions

new YurbaUI.Tooltip(el, { pos: 'top',    title: 'Title', content: 'Content' })
new YurbaUI.Tooltip(el, { pos: 'bottom', title: 'Title', content: 'Content' })
new YurbaUI.Tooltip(el, { pos: 'left',   title: 'Title', content: 'Content' })
new YurbaUI.Tooltip(el, { pos: 'right',  title: 'Title', content: 'Content' })

With icon

new YurbaUI.Tooltip(el, {
    pos: 'top',
    title: 'With icon',
    content: 'This tooltip has an icon',
    icon: '<span class="material-symbols-rounded">info</span>'
})

Custom header color via className

new YurbaUI.Tooltip(el, {
    pos: 'top',
    title: 'Info badge',
    content: 'Styled with className',
    className: 'popover-info'   // popover-info | popover-default | popover-danger
})

YurbaUI.Select

Styled dropdown select component. Renders inside any container and supports icons, default values, and programmatic control. Automatically repositions if near screen edges.

Constructor

const select = new YurbaUI.Select(options[], settings?)

Option shape

Field	Type	Required	Description
`value`	string	required	Internal value identifier.
`label`	string	required	Display text shown in the dropdown and trigger.
`icon`	string	optional	Icon HTML string or emoji shown next to the label.

Settings

Setting	Type	Default	Description
`value` optional	string	—	Initially selected value (single mode).
`multiple` optional	boolean	`false`	Enables multi-select mode with checkboxes. Menu stays open on click.
`values` optional	string[]	`[]`	Initially selected values (multi mode).
`placeholder` optional	string	—	Placeholder text shown when nothing is selected.

Methods

Method	Params	Returns	Description
`render()`	—	HTMLElement	Returns the component root element. Append it to the DOM.
`getValue()`	—	string \| string[]	Returns the selected value. In multi mode returns an array.
`setValue(value)`	`value` — string \| string[]	this	Programmatically sets the selected value(s) and updates the trigger label.
`onChange(callback)`	single: `callback(value, option)` multi: `callback(values[], options[])`	this	Registers a handler called whenever the selection changes.

Events

The select dispatches a bubbling CustomEvent on its root element (the node returned by render()). Listen with addEventListener, or use the onChange() method for a callback equivalent.

Event	Fires on	Description
`yurba-select:change`	`select.render()`	The user picked an option. `detail` is `{ value, option }` (single) or `{ values, options }` (multi). Programmatic `setValue()` does not fire it.

const select = new YurbaUI.Select(options)
const el = select.render()
container.appendChild(el)

el.addEventListener('yurba-select:change', (e) => {
    console.log(e.detail.value)   // single: e.detail.option; multi: e.detail.values / .options
})

Demo

Basic

const select = new YurbaUI.Select([
    { value: 'apple',  label: 'Apple' },
    { value: 'banana', label: 'Banana' },
    { value: 'cherry', label: 'Cherry' },
])
select.onChange((value) => console.log('Selected:', value))
container.appendChild(select.render())

With icons and default value

const select = new YurbaUI.Select([
    { value: 'public',  label: 'Public',  icon: '🌍' },
    { value: 'friends', label: 'Friends', icon: '👥' },
    { value: 'private', label: 'Only me', icon: '🔒' },
], { value: 'public' })
select.onChange((value, option) => console.log(value, option))

Multi-select

const select = new YurbaUI.Select([
    { value: 'read',    label: 'Read' },
    { value: 'write',   label: 'Write' },
    { value: 'delete',  label: 'Delete' },
    { value: 'admin',   label: 'Admin' },
], { multiple: true, values: ['read', 'write'] })
select.onChange((values) => console.log(values))
container.appendChild(select.render())

Many options (scroll)

const options = Array.from({ length: 20 }, (_, i) => ({
    value: `opt${i}`,
    label: `Option ${i + 1}`,
}))
const select = new YurbaUI.Select(options, { multiple: true })
container.appendChild(select.render())

YurbaUI.Dropdown

Panel anchored to a trigger button. Works in two modes: items[] for simple action menus (with icons, separators, callbacks), or custom content for arbitrary HTML panels (notifications, user menus, etc.). Repositions automatically near screen edges. Dispatches yurba-dropdown:open / yurba-dropdown:close events on the menu element.

Constructor

const dropdown = new YurbaUI.Dropdown(items[], options?)

Item shape

Field	Type	Description
`label`	string	Item text. Not needed when `separator: true`.
`icon`	string	Raw HTML icon string shown before the label.
`className`	string	One or more CSS classes added to the item `<button>`. Use `'text-danger'` for destructive actions.
`separator`	boolean	When `true`, renders a horizontal divider instead of a button.
`children`	array	Nested item array. The item becomes a parent that opens a submenu on hover.
`submenu`	HTMLElement \| string	Custom HTML rendered inside the submenu instead of nested items. Use for inline controls (e.g. a date picker). Combine with `onClick` to also make the parent itself actionable.
`onClick`	function	Click handler called when the item is selected. Works on leaf and parent items alike.

Options

Option	Type	Default	Description
`trigger` required	string	—	Raw HTML rendered inside the trigger button.
`content` optional	HTMLElement \| string	—	Custom content rendered inside the panel. When set, `items[]` is ignored.
`onOpen` optional	function	—	Called when the panel opens. Receives the menu `HTMLElement`. Use for lazy data loading.
`onClose` optional	function	—	Called when the panel closes.
`align` optional	string	`'left'`	Horizontal alignment of the menu relative to the trigger. `'left'` — menu left edge aligns with trigger; `'right'` — menu right edge aligns with trigger.
`triggerClass` optional	string	—	Space-separated CSS classes added to the trigger `<button>`. E.g. `'btn btn-clear'`.

Methods

Method	Params	Returns	Description
`render()`	—	HTMLElement	Returns the wrapper element (trigger + menu). Append it to the DOM. Sets `.menu` property.

Events

The dropdown dispatches bubbling CustomEvents on its menu element (dropdown.menu). Listen with addEventListener, or use the onOpen / onClose options for a callback equivalent.

Event	Fires on	Description
`yurba-dropdown:open`	`dropdown.menu`	The panel became visible.
`yurba-dropdown:close`	`dropdown.menu`	The panel was hidden (item click, trigger toggle, or outside click).

const dropdown = new YurbaUI.Dropdown(items, { trigger: '...' })
container.appendChild(dropdown.render())

dropdown.menu.addEventListener('yurba-dropdown:open', () => {
    console.log('opened')
})
dropdown.menu.addEventListener('yurba-dropdown:close', () => {
    console.log('closed')
})

Demo

Items menu

const dropdown = new YurbaUI.Dropdown([
    { label: 'Edit',   icon: '<span class="material-symbols-rounded">edit</span>' },
    { label: 'Share',  icon: '<span class="material-symbols-rounded">share</span>' },
    { separator: true },
    {
        label: 'Delete',
        icon: '<span class="material-symbols-rounded">delete</span>',
        className: 'text-danger',
        onClick: () => console.log('Delete')
    },
], { trigger: '<span class="material-symbols-rounded">more_vert</span>' })
container.appendChild(dropdown.render())

Nested (multi-level)

const dropdown = new YurbaUI.Dropdown([
    { label: 'Edit', icon: '...', onClick: () => {} },
    {
        label: 'Share',
        icon: '...',
        children: [
            { label: 'Copy link', icon: '...', onClick: () => {} },
            {
                label: 'Send to',
                icon: '...',
                children: [
                    { label: 'Message', onClick: () => {} },
                    { label: 'Email',   onClick: () => {} },
                ]
            },
        ]
    },
    { separator: true },
    { label: 'Delete', className: 'text-danger', onClick: () => {} },
], { trigger: '...' })
container.appendChild(dropdown.render())

Custom content panel

const panel = document.createElement('div')
panel.style.padding = '12px'
panel.innerHTML = '<p>Loading...</p>'

const dropdown = new YurbaUI.Dropdown([], {
    trigger: '<span class="material-symbols-rounded">notifications</span>',
    content: panel,
    onOpen: (menu) => {
        // lazy load — called once per open
        panel.innerHTML = '<p>No new notifications</p>'
    },
})

// DOM event alternative
dropdown.render()
dropdown.menu.addEventListener('yurba-dropdown:open', () => {
    console.log('opened')
})
container.appendChild(dropdown.el)

YurbaUI.ContextMenu

Right-click context menu built on the same item model as Dropdown — icons, separators, callbacks, and nested submenus. Opens at the cursor with position: fixed, repositions near screen edges, and closes on outside click, scroll, or Esc. Bind it to any element (or selector) via bind(), or open it manually at coordinates with open(x, y).

Constructor

const menu = new YurbaUI.ContextMenu(items[], options?)

Item shape

Identical to YurbaUI.Dropdown items — label, icon, className, separator, onClick, and children[] for nested submenus.

Field	Type	Description
`label`	string	Item text. Not needed when `separator: true`.
`icon`	string	Raw HTML icon string shown before the label.
`className`	string	CSS classes added to the item `<button>`. Use `'text-danger'` for destructive actions.
`separator`	boolean	Renders a horizontal divider instead of a button.
`children`	array	Nested item array. Opens as a submenu on hover.
`submenu`	HTMLElement \| string	Custom HTML rendered inside the submenu instead of nested items.
`onClick`	function	Click handler. The menu closes automatically after it runs.

Options

Option	Type	Description
`onOpen` optional	function	Called when the menu opens. Receives `(menuEl, target)`.
`onClose` optional	function	Called when the menu closes. Receives `(target)`.

Methods

Method	Params	Returns	Description
`bind(target)`	`target` — HTMLElement \| NodeList \| Array \| CSS selector string	this	Attaches a `contextmenu` (right-click) handler to one or many elements.
`open(x, y, target?)`	`x`, `y` — viewport coordinates	HTMLElement	Opens the menu manually at the given coordinates. Returns the menu element.
`close()`	—	void	Closes the menu and removes it from the DOM.
`isOpen()`	—	boolean	Returns `true` while the menu is visible.

Demo

Right-click target — bind()

const menu = new YurbaUI.ContextMenu([
    { label: 'Open',   icon: '<span class="material-symbols-rounded">open_in_new</span>', onClick: () => {} },
    { label: 'Rename', icon: '<span class="material-symbols-rounded">edit</span>',        onClick: () => {} },
    { separator: true },
    { label: 'Delete', icon: '<span class="material-symbols-rounded">delete</span>', className: 'text-danger', onClick: () => {} },
])
menu.bind('#context-target')

Right-click here

Nested submenus

const menu = new YurbaUI.ContextMenu([
    { label: 'Cut',  icon: '...', onClick: () => {} },
    { label: 'Copy', icon: '...', onClick: () => {} },
    {
        label: 'Share',
        icon: '...',
        children: [
            { label: 'Copy link', icon: '...', onClick: () => {} },
            {
                label: 'Send to',
                icon: '...',
                children: [
                    { label: 'Message', onClick: () => {} },
                    { label: 'Email',   onClick: () => {} },
                ]
            },
        ]
    },
    { separator: true },
    { label: 'Delete', className: 'text-danger', onClick: () => {} },
])
menu.bind('#context-target-nested')

Right-click here

Open manually at coordinates — open(x, y)

const menu = new YurbaUI.ContextMenu([
    { label: 'Profile',  icon: '...', onClick: () => {} },
    { label: 'Settings', icon: '...', onClick: () => {} },
    { separator: true },
    { label: 'Log out',  icon: '...', className: 'text-danger', onClick: () => {} },
])

button.addEventListener('click', (e) => {
    const r = e.currentTarget.getBoundingClientRect()
    menu.open(r.left, r.bottom)
})

YurbaUI.Readmore

Collapses tall content to a fixed height and appends a toggle button to expand or collapse it. No wrapping element needed.

Constructor

new YurbaUI.Readmore(target, options?)

Option	Type	Default	Description
`target` required	HTMLElement \| string	—	Element to collapse, or a CSS selector string.
`collapsedHeight` optional	number	`200`	Height in pixels when collapsed.
`heightMargin` optional	number	`16`	If the content is within this many pixels of `collapsedHeight`, it is not collapsed at all.
`moreText` optional	string	`'Read more'`	Label on the toggle button when collapsed.
`lessText` optional	string	`'Read less'`	Label on the toggle button when expanded.

new YurbaUI.Readmore(document.querySelector('.post-content'), {
    collapsedHeight: 200,
    heightMargin: 16,
    moreText: 'Read more',
    lessText: 'Read less',
})

If a CSS selector string is passed, document.querySelector() is used. The toggle button is inserted immediately after the target element and is not a child of it.

Methods

Method	Description
`expand()`	Expand to full height.
`collapse()`	Collapse back to `collapsedHeight`.

Demo

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo.

Components & Placements

Content components passed to modal.renderComponent(component, placement?). Each component extends BaseComponent and carries a default placement that can be overridden.

Placements

modal.renderComponent(component, placement?)

Value	Area	Description
`'body'`	`modal.modalBody`	Main scrollable content area. Default for most components.
`'header'`	`modal.modalHeader`	Above the body. Default for Title, Description, TitleIcon.
`'footer'`	`modal.modalFooterBody`	Action bar below the body. Typically holds IconButton actions.
`'controls'`	`modal.modalControls`	Top-right slot next to the close button. For auxiliary icon controls.

Default placement: when placement is omitted, each component uses its own default (shown per component below).

YurbaUI.Title

new YurbaUI.Title(text)

Param	Type	Description
`text`	string	Title text. HTML is supported.

Default placement: 'header'

YurbaUI.Description

new YurbaUI.Description(text)

Param	Type	Description
`text`	string	Subtitle/description text shown beneath the title. HTML is supported.

Default placement: 'header'

YurbaUI.Text

new YurbaUI.Text(html)

Param	Type	Description
`html`	string	Body paragraph content. Renders as `<p>`. Full HTML support.

Default placement: 'body'

YurbaUI.Image

new YurbaUI.Image(url)

Param	Type	Description
`url`	string	Image URL. Renders as a full-width `<img>`.

Default placement: 'body'

YurbaUI.IconButton

new YurbaUI.IconButton({ icon, name? }, onClick?)

Option	Type	Description
`icon`	string	Raw HTML icon string.
`name` optional	string	Label shown below the icon. When omitted the button renders icon-only.
`onClick` optional	function	Second argument — click handler called when the button is pressed.

Default placement: 'body'. Commonly placed in 'footer' or 'controls'.

YurbaUI.TitleIcon

new YurbaUI.TitleIcon({ icon, type? })

Option	Type	Default	Description
`icon`	string	—	Raw HTML icon string displayed as the modal's decorative icon.
`type` optional	string	`'default'`	CSS type class applied to the icon container for color theming.

Default placement: 'header'

YurbaUI.MaterialIcon

new YurbaUI.MaterialIcon(name)

Param	Type	Description
`name`	string	Material Symbols icon name (e.g. `'check'`, `'edit'`). Renders as `<span class="material-symbols-rounded">`.

Default placement: 'body'. Requires Material Symbols font to be loaded.

YurbaUI.YurbaIcon

new YurbaUI.YurbaIcon(name)

Param	Type	Description
`name`	string	Yurba icon name. Renders as `<span class="yrb yrb-{name}">`.

Default placement: 'body'. Requires the Yurba icon font.

YurbaUI.Group

const group = new YurbaUI.Group(...components)

// Add components after creation
group.add(component)

// Apply CSS classes to the group wrapper
group.addClass('my-class', 'another-class')

Wraps multiple components in a single .y-win__group container. Duplicate components are silently ignored. Default placement: 'body'.

Method	Params	Returns	Description
`add(component)`	`component` — BaseComponent	void	Appends a component to the group after construction.
`addClass(...names)`	`...names` — string	void	Adds one or more CSS classes to the group wrapper element.