Components - VelinStyle

velin-modal

Accessible modal dialog with focus trapping and Escape to close.

Attributes

Name	Type	Default	Description
`title`	string	`""`	Modal heading text
`open`	boolean	`false`	Show/hide the modal (reflected)

Methods

Name	Description
`open()`	Opens the modal, traps focus
`close()`	Closes the modal, restores focus

Events

Name	Detail
`velin-close`	Fired when modal is closed

Slots

Name	Description
(default)	Modal body content
`footer`	Footer area (action buttons)

velin-tabs

Tabbed interface with roving tabindex and arrow key navigation.

VelinStyle tabs use native roving tabindex. Arrow keys navigate between tabs.

Keyboard navigation
Automatic ARIA
Panel show/hide

Listen to velin-tab-change for tab switch events.

Events

Name	Detail
`velin-tab-change`	`{ tab, index }`

Slots

Name	Description
`tab`	Tab buttons with `role="tab"` (set `aria-selected="true"` for default)
`panel`	Tab panel content (matched by order)

velin-accordion

Native <details>/<summary> with optional exclusive mode. Arrow keys navigate between items. Panel styles use light-DOM CSS (slotted descendants cannot be styled with ::slotted()).

What is VelinStyle?

An accessibility-first CSS framework.

How do I install it?

npm install velinstyle

Can I customize it?

Yes! Override CSS custom properties or use theme presets.

Attributes

Name	Type	Default	Description
`exclusive`	boolean	`false`	Only one item open at a time

Keyboard

Key	Action
ArrowUp/Down	Navigate between summaries
Home / End	Jump to first/last item
Enter / Space	Toggle the focused item (native details)

velin-toast

Notification toasts with aria-live region.

Methods

Name	Parameters	Description
`show(options)`	`{ message, type, duration }`	Show a toast. Types: `success`, `warning`, `danger`, `info`. Duration in ms (0 = sticky).

velin-dropdown

Dropdown menu with keyboard navigation and outside-click closing.

Attributes

Name	Type	Default	Description
`open`	boolean	`false`	Toggle menu visibility
`align`	string	`"start"`	Menu alignment: `start` or `end`

Methods

Name	Description
`open()`	Open the dropdown
`close()`	Close the dropdown
`toggle()`	Toggle open/close

Slots

Name	Description
`trigger`	Button that opens the menu
(default)	Menu items (`<button>` or links; slotted into `role="menu"`)

velin-drawer

Slide-in panel with focus trapping. Supports all 4 sides.

Settings panel content goes here.

Attributes

Name	Type	Default	Description
`title`	string	`""`	Drawer heading
`side`	string	`"start"`	Position: `start`, `end`, `top`, `bottom`
`open`	boolean	`false`	Show/hide (reflected)

Methods

Name	Description
`open()`	Open the drawer
`close()`	Close the drawer

Events

Name	Detail
`velin-close`	Fired on close

velin-popover

Popover with click, hover, or focus trigger. Auto role (tooltip/dialog).

This popover opens on click. Press Escape to close.

This popover opens on hover/focus.

Attributes

Name	Type	Default	Description
`placement`	string	`"bottom"`	`top`, `bottom`, `start`, `end`
`trigger`	string	`"click"`	`click`, `hover`, `focus`
`title`	string	`""`	Popover heading (optional)

Methods

Name	Description
`open()` / `close()` / `toggle()`	Programmatic control

velin-tooltip

Pure-CSS tooltip with auto-flip and keyboard support.

Attributes

Name	Type	Default	Description
`content`	string	`""`	Tooltip text (XSS-safe)
`placement`	string	`"top"`	`top`, `bottom`, `start`, `end`

velin-collapse

Expandable/collapsible content section.

This content can be expanded and collapsed. Supports open(), close(), and toggle() methods.

Attributes

Name	Type	Default	Description
`open`	boolean	`false`	Expanded state (reflected)

Methods

Name	Description
`open()` / `close()` / `toggle()`	Programmatic expand/collapse

Events

Name	Detail
`velin-open`	Fired when expanded
`velin-close`	Fired when collapsed

velin-carousel

Image/content carousel with keyboard navigation and autoplay.

Slide 1

Slide 2

Slide 3

Attributes

Name	Type	Default	Description
`autoplay`	boolean	`false`	Auto-advance slides
`interval`	number	`5000`	Autoplay interval in ms

Keyboard

Key	Action
ArrowLeft / ArrowRight	Previous / Next slide
Home / End	First / Last slide

Events

Name	Detail
`velin-slide-change`	`{ index }`

velin-lightbox

Fullscreen image/video gallery with focus trapping and keyboard navigation.

Image 1

Image 2

Image 3

Click any image to open lightbox. Arrow keys to navigate.

Methods

Name	Description
`open(index)`	Open lightbox at slide index
`close()`	Close lightbox

Events

Name	Detail
`velin-close`	Fired on close

velin-dialog

Native <dialog> wrapper for alert, confirm, and prompt. Returns a Promise.

Methods

Name	Parameters	Returns
`alert(message, opts)`	`{ title, confirmText }`	`Promise<true>`
`confirm(message, opts)`	`{ title, confirmText, cancelText, danger }`	`Promise<boolean>`
`prompt(message, opts)`	`{ title, confirmText, cancelText, placeholder, defaultValue }`	`Promise<string\|null>`

Events

Name	Detail
`velin-dialog-close`	`{ value }`

velin-stepper

Multi-step progress indicator with panel management.

Step 1: Create your account.

Step 2: Fill in your profile details.

Step 3: Review and confirm everything.

Attributes

Name	Type	Default	Description
`labels`	string	`""`	Comma-separated step labels
`active`	number	`0`	Current active step (0-based)

Methods

Name	Description
`next()`	Go to next step
`prev()`	Go to previous step
`goTo(index)`	Jump to specific step

Events

Name	Detail
`velin-step-change`	`{ step }`

velin-countdown

Live countdown timer with role="timer" and aria-live.

Attributes

Name	Type	Description
`datetime`	string	ISO date string target (e.g. `2027-01-01T00:00:00`)
`show-days`	string	Set `"false"` to hide days segment
`label-days`	string	Custom label for days (default: "Days")
`label-hours`	string	Custom label for hours
`label-minutes`	string	Custom label for minutes
`label-seconds`	string	Custom label for seconds
`size`	string	`sm` or `lg` for size variants

Events

Name	Detail
`velin-countdown-end`	Fired when countdown reaches zero

velin-progress-ring

Circular progress indicator with role="progressbar".

Value: 65%

Attributes

Name	Type	Default	Description
`value`	number	`0`	Progress value (0-100)
`size`	number	`60`	Diameter in pixels
`stroke`	number	`4`	Stroke width
`color`	string	primary	CSS color for the progress arc

velin-copy

One-click copy-to-clipboard button.

Click to copy npm install velinstyle to clipboard.

Attributes

Name	Type	Description
`value`	string	Text to copy to clipboard

Events

Name	Detail
`velin-copied`	Fired after successful copy

velin-theme-toggle

Light/dark mode toggle with localStorage persistence. Click the button to switch between light and dark mode.

Current: light

Attributes

Name	Type	Default	Description
`target`	string	`"html"`	CSS selector for element to toggle `data-velin-theme` on

Events

Name	Detail
`velin-theme-change`	`{ theme, dark }`

velin-scroll-top

Floating back-to-top button that appears on scroll.

Scroll down the page to see the button appear in the bottom-right corner.

Attributes

Name	Type	Default	Description
`threshold`	number	`300`	Scroll distance (px) before button appears

Custom Properties

Property	Default	Description
`--velin-scroll-top-bottom`	`1rem`	Bottom offset
`--velin-scroll-top-end`	`1rem`	Inline-end offset

velin-scrollspy

Highlights navigation links based on scroll position.

Wrap a <nav> with links that match section IDs. As user scrolls, active link gets highlighted.

<velin-scrollspy>
  <nav>
    <a href="#section-1">Section 1</a>
    <a href="#section-2">Section 2</a>
  </nav>
</velin-scrollspy>

Events

Name	Detail
`velin-spy-change`	`{ id, link }` of the currently active section

velin-persist

Auto-saves form data to localStorage. Survives page reload. Password/file fields excluded for security.

Type something, reload the page -- your input persists!

Attributes

Name	Type	Default	Description
`key`	string	`"default"`	Storage key identifier (alphanumeric, max 64 chars)
`storage`	string	`"local"`	`"local"` or `"session"` for sessionStorage

Methods

Name	Description
`clear()`	Remove saved data from storage

Events

Name	Detail
`velin-persist-restore`	`{ data }` -- Fired after data is restored from storage
`velin-persist-clear`	Fired after data is cleared
`velin-persist-error`	`{ error: "quota" }` -- Storage quota exceeded

velin-haptic (Utility)

Device vibration feedback for buttons and interactions. Works on supported mobile devices.

Add haptic="pattern" to any element. Patterns: tap, double-tap, error, success, warning.

HTML API

Attribute	Values	Description
`haptic`	`tap`, `double-tap`, `error`, `success`, `warning`	Vibration pattern triggered on click

JS API

Export	Description
`vibrate(pattern)`	Trigger vibration with a duration array
`applyHaptic(el, pattern)`	Bind haptic click handler to element
`VelinHapticObserver`	MutationObserver that auto-applies `[haptic]` attribute

velin-icon

SVG icon component with multi-provider support. See Icons page for the full icon gallery.

<!-- Local sprite (default) -->
<velin-icon name="check" size="24"></velin-icon>

<!-- External provider (CDN) -->
<velin-icon name="heart" provider="lucide"></velin-icon>
<velin-icon name="academic-cap" provider="heroicons"></velin-icon>

<!-- Custom sprite -->
<velin-icon name="custom" sprite="my-icons.svg"></velin-icon>

Attributes

Name	Type	Default	Description
`name`	string	required	Icon name
`size`	number	`24`	Width and height in pixels
`label`	string	`""`	Accessible label (sets `role="img"` + `aria-label`)
`sprite`	string	`"velin-icons.svg"`	Custom sprite path
`provider`	string	`""`	External icon provider: `lucide`, `heroicons`, `bootstrap`, `material`, `fontawesome`, `tabler`

Providers

Provider	Icons	License
`lucide`	Lucide (Feather fork)	ISC
`heroicons`	Heroicons (Tailwind Labs)	MIT
`bootstrap`	Bootstrap Icons	MIT
`material`	Material Symbols (Google)	Apache 2.0
`fontawesome`	Font Awesome (Free)	CC BY 4.0
`tabler`	Tabler Icons	MIT

JS API

Method	Description
`VelinIcon.registerProvider(name, urlTemplate)`	Register a custom icon provider at runtime. Use `{name}` as placeholder.
`VelinIcon.providers`	Returns array of registered provider keys

CLI

Command	Description
`velinstyle icons list`	Show available providers and installed icons
`velinstyle icons add <provider> --icons name1,name2`	Download icons from a provider into the local sprite
`velinstyle icons remove <provider>`	Remove all icons from a provider
`velinstyle icons build`	Rebuild the SVG sprite

velin-combobox

Autocomplete listbox with a trigger in the trigger slot.

Events	Detail
`velin-select`	`{ option }`

velin-bottom-nav

Mobile bottom navigation; set current to match data-nav on links.

Home Search Profile

velin-sheet

Bottom sheet with focus trap. Methods: open(), close().

Sheet body.

velin-segmented-control

velin-rating

velin-menubar

velin-calendar

Month calendar. value (ISO date), optional min/max, event velin-change. Keyboard: arrows, Home/End, PageUp/Down, Enter.

velin-file-dropzone

Client-side dropzone. Events velin-files / velin-error. Does not upload to a server — wire your API.

velin-command

Command palette. Close with Escape, backdrop click, or toggle(). Closed overlay does not intercept pointer events.

Methods

Name	Description
`open()`	Open the palette
`close()`	Close the palette
`toggle()`	Toggle open/close

velin-announcer

Live region for screen readers. Static helper: VelinAnnouncer.announceGlobal().

Web Components

velin-modal

Attributes

Methods

Events

Slots

velin-tabs

Events

Slots

velin-accordion

Attributes

Keyboard

velin-toast

Methods

velin-dropdown

Attributes

Methods

Slots

velin-drawer

Attributes

Methods

Events

velin-popover

Attributes

Methods

velin-tooltip

Attributes

velin-collapse

Attributes

Methods

Events

velin-carousel

Attributes

Keyboard

Events

velin-lightbox

Methods

Events

velin-dialog

Methods

Events

velin-stepper

Attributes

Methods

Events

velin-countdown

Attributes

Events

velin-progress-ring

Attributes

velin-copy

Attributes

Events

velin-theme-toggle

Attributes

Events

velin-scroll-top

Attributes

Custom Properties

velin-scrollspy

Events

velin-persist

Attributes

Methods

Events

velin-haptic (Utility)

HTML API

JS API

velin-icon

Attributes

Providers

JS API

CLI

velin-combobox

velin-bottom-nav

velin-sheet

velin-segmented-control

velin-rating

velin-menubar

velin-calendar