jb-button

jb-button

simple button web-component with some additional features:

• custom styling

• support loading state

• typescript ready

• compatible with form elements

When to use

Use jb-button for actions that need JB Design System styling, loading state, disabled state, or form submit behavior.

Try the component in CodePen or explore the complete Demo.

Using With JS Frameworks

Other integrations: Angular · Vue · Nuxt · Svelte · SvelteKit · SolidJS · Lit · Next.js · Astro · Blazor · Server-rendered templates · WordPress · Alpine.js and HTMX

Installation

using npm

npm i jb-button

We must import package in one of our js files.

import 'jb-button';

in your html or jsx

<jb-button>Save</jb-button>

using cdn

you can just add script tag to your html file and then use web component however you need

<script src="https://unpkg.com/jb-button/dist/JBButton.umd.js"></script>

API reference

Attributes

name	type	default	description
type	'button' | 'submit' | 'reset' | string	browser default	Forwarded to the inner native button. When set to submit, jb-button calls the associated form requestSubmit() after a non-canceled click. Demo
name	string	null	Forwarded to the inner native button.
disabled	boolean	false	Disables the inner button and sets the disabled custom state. Demo
is-loading	boolean	false	Shows the loading UI. Loading does not automatically disable the button.
loading-text	string	""	Text shown beside the loading indicator while loading. Demo
button-style	string	""	Inline style forwarded to the inner button. Prefer CSS variables for reusable styling. Demo
color	'primary' | 'secondary' | 'positive' | 'danger' | 'warning' | 'light' | 'dark'	primary	Visual color token used by CSS. Demo
variant	'solid' | 'outline' | 'ghost' | 'text'	solid	Visual variant used by CSS. Demo
size	'xs' | 'sm' | 'md' | 'lg' | 'xl'	md style defaults	Visual size used by CSS. Demo
square	boolean	false	Makes inline padding equal to block padding, ignoring --jb-button-inline-padding. Demo

Properties

name	type	readonly	description
isLoading	boolean	no	Shows or hides the loading UI. Demo
loadingText	string	no	Text shown beside the loading indicator.
disabled	boolean	no	Enables or disables the component.
name	string | null	no	Reflects the name attribute.

Events

event	cancelable	when it fires
click	yes	Re-dispatched from the inner native button. Call event.preventDefault() to stop the inner click behavior and prevent form submit. Demo

const button = document.querySelector('jb-button');

button.addEventListener('click', (event) => {
  console.log('clicked', event.target);
});

Square buttons

Use the square attribute for compact icon buttons or other controls that need equal inline and block padding. The button uses its resolved block padding on both axes, including size-specific block padding; see the Demo.

<jb-button square aria-label="Add item">+</jb-button>

Loading state

You can show loading by setting element.isLoading = true; see the Demo. For a non-interactive loading state, see the disabled loading Demo.

const button = document.querySelector('jb-button');
button.isLoading = true;
button.loadingText = 'Saving';

You can also set loading text in markup:

<jb-button is-loading loading-text="Saving">Save</jb-button>

When the button is loading, the slotted button content is hidden and the loading indicator is shown. Disable the button separately if the user must not click it while loading:

<jb-button is-loading disabled loading-text="Saving">Save</jb-button>

Form usage

jb-button is form-associated. When type="submit" and the click event is not canceled, the component calls requestSubmit() on its associated form; see the Demo.

<form>
  <jb-button type="submit">Submit</jb-button>
</form>

Slot

jb-button has a default slot for button content. You can pass text, icons, or both; see the button-content Demo.

<jb-button>
  <svg aria-hidden="true"></svg>
  Save
</jb-button>

Icons in button content

Slotted svg and img elements are automatically sized to match the button's icon size. You can apply the icon class to another slotted element to give it the same behavior:

<jb-button size="lg">
  <span class="icon" aria-hidden="true">+</span>
  Add item
</jb-button>

The .icon element receives the button's resolved icon width and height, which change with the button's size attribute. This also works with custom icon elements:

<jb-button>
  <my-add-icon class="icon" aria-hidden="true"></my-add-icon>
  Add item
</jb-button>

change button style

For complete styling guidance, live examples, and copyable style recipes, see Styling.

The default and xs, sm, lg, and xl button heights inherit the matching --jb-control-height-* theme tokens. Set --jb-button-height or a size-specific --jb-button-height-* variable when one button needs a component-level override.

you can inject your custom style by attribute to button.

<jb-button button-style="height:2.25rem;"></jb-button>

the other way of injecting style to jb-button is by providing CSS variable in component parent element to set some attribute for example to set button height:

.your-jb-button-wrapper{
    /*default height of button is 2.75rem but it will change it to 2.5rem*/
    --jb-button-height: 2.5rem;
    /* set button margin for example for zero margin:*/
    --jb-button-margin: 0 0;
}

You can also style the host for state-specific situations:

jb-button:state(disabled) {
  --jb-button-box-shadow: none;
}

jb-button[variant="outline"][color="danger"] {
  --jb-button-border-width: 2px;
}

in some cases in your project you need to change default style of web-component for example you need zero margin or different border-radius and etc. if you want to set a custom style to this web-component all you need is to set CSS variable in parent scope of web-component

CSS variable name	description
--jb-button-margin	web-component margin
--jb-button-inline-padding	button inline padding
--jb-button-block-padding	button block padding
--jb-button-border-radius	web-component border-radius
--jb-button-bg-color-hover	button bg-color when user hover
--jb-button-bg-color-pressed	button bg-color when user pressed
--jb-button-height	button height default is 2.75rem
--jb-button-text-shadow	button text shadow
--jb-button-color	color of text in button
--jb-button-box-shadow	button box shadow; defaults to --jb-control-shadow
--jb-corner-shape	button corner shape token
--jb-button-font-weight	font weight of button default is bold
--jb-button-font-size	font size of button default is 1.2em
--jb-button-color-hover	color of button in hover state
--jb-button-cursor	change button cursor default is pointer
--jb-button-color-disabled	color of button when disabled
--jb-button-cursor-disabled	cursor of button when disabled
--jb-button-text-shadow-disabled	text shadow of button when disabled
--jb-button-loading-color	jb-loading icon color default is text color value
--jb-button-loading-color-disabled	jb-loading icon color when disabled default is text color value
--jb-button-loading-color-outline	Customize outline variant loading color.
--jb-button-loading-color-outline-disabled	Customize disabled outline variant loading color.
--jb-button-loading-color-ghost	Customize ghost variant loading color.
--jb-button-loading-color-text	Customize text variant loading color.
--jb-button-bg-color	Customize bg-color.
--jb-button-bg-color-text	Customize text variant bg-color.
--jb-button-bg-color-text-hover	Customize text variant bg-color hover.
--jb-button-bg-color-text-pressed	Customize text variant bg-color pressed.
--jb-button-bg-color-ghost	Customize bg-color ghost.
--jb-button-bg-color-ghost-hover	Customize bg-color ghost hover.
--jb-button-bg-color-ghost-pressed	Customize bg-color ghost pressed.
--jb-button-bg-color-outline	Customize bg-color outline.
--jb-button-bg-color-outline-hover	Customize bg-color outline hover.
--jb-button-bg-color-outline-pressed	Customize bg-color outline pressed.
--jb-button-border-color	Customize border color.
--jb-button-border-color-hover	Customize border color hover.
--jb-button-border-color-pressed	Customize border color pressed.
--jb-button-border-radius-lg	Customize border radius lg.
--jb-button-border-radius-sm	Customize border radius sm.
--jb-button-border-radius-xl	Customize border radius xl.
--jb-button-border-radius-xs	Customize border radius xs.
--jb-button-border-style	Customize border style.
--jb-button-border-width	Customize border width.
--jb-button-border-width-ghost	Customize ghost variant border width.
--jb-button-border-width-text	Customize text variant border width.
--jb-button-content-gap	Customize content gap.
--jb-button-content-gap-xs	Customize content gap xs.
--jb-button-content-gap-sm	Customize content gap sm.
--jb-button-content-gap-lg	Customize content gap lg.
--jb-button-content-gap-xl	Customize content gap xl.
--jb-button-color-pressed	Customize color pressed.
--jb-button-color-outline	Customize outline variant color.
--jb-button-color-outline-hover	Customize outline variant color hover.
--jb-button-color-outline-pressed	Customize outline variant color pressed.
--jb-button-color-outline-disabled	Customize disabled outline variant color.
--jb-button-color-ghost	Customize ghost variant color.
--jb-button-color-ghost-hover	Customize ghost variant color hover.
--jb-button-color-ghost-pressed	Customize ghost variant color pressed.
--jb-button-color-text	Customize text variant color.
--jb-button-color-text-hover	Customize text variant color hover.
--jb-button-color-text-pressed	Customize text variant color pressed.
--jb-button-danger	Customize danger.
--jb-button-dark	Customize dark.
--jb-button-disabled	Customize disabled.
--jb-button-font-size-lg	Customize font size lg.
--jb-button-font-size-sm	Customize font size sm.
--jb-button-font-size-xl	Customize font size xl.
--jb-button-font-size-xs	Customize font size xs.
--jb-button-height-lg	Customize height lg.
--jb-button-height-sm	Customize height sm.
--jb-button-height-xl	Customize height xl.
--jb-button-height-xs	Customize height xs.
--jb-button-icon-size	Customize icon size.
--jb-button-icon-size-lg	Customize icon size lg.
--jb-button-icon-size-sm	Customize icon size sm.
--jb-button-icon-size-xl	Customize icon size xl.
--jb-button-icon-size-xs	Customize icon size xs.
--jb-button-light	Customize light.
--jb-button-inline-padding-lg	Customize inline padding lg.
--jb-button-inline-padding-sm	Customize inline padding sm.
--jb-button-inline-padding-xl	Customize inline padding xl.
--jb-button-inline-padding-xs	Customize inline padding xs.
--jb-button-block-padding-lg	Customize block padding lg.
--jb-button-block-padding-sm	Customize block padding sm.
--jb-button-block-padding-xl	Customize block padding xl.
--jb-button-block-padding-xs	Customize block padding xs.
--jb-button-positive	Customize positive.
--jb-button-primary	Customize primary.
--jb-button-secondary	Customize secondary.
--jb-button-warning	Customize warning.

Related Docs

• see jb-button/react; if you want to use this component in react

• see All JB Design system Component List for more components

• use Contribution Guide if you want to contribute in this component.

AI agent notes

This package includes custom-elements.json so documentation tools, IDEs, and AI coding agents can discover the tag name, attributes, events, slot, CSS variables, and public properties.

The package also exposes "customElements": "custom-elements.json" in package.json, which gives tools a stable package-level pointer to the manifest. This field is documented by the Custom Elements Manifest project in its Referencing manifests from npm packages section.

In custom-elements.json, the exports array describes what this module makes available:

kind	meaning
js	A JavaScript/TypeScript export from the module, such as JBButtonWebComponent.
custom-element-definition	The custom element registration for a tag name, such as jb-button.

Each export points to a declaration with name and module, so tools can connect the public export or tag name back to the class metadata.

• Import jb-button once before using <jb-button>.
• Put visible button content in the default slot.
• Use isLoading for loading UI and disabled when clicks must be blocked.
• Use square for icon-only or compact buttons that need equal inline and block padding.
• Use type="submit" only inside forms where submitting is intended.
• Use event.preventDefault() on click to cancel the component click behavior.