jb-input

jb-input

text input web component with these benefit:

• easy to add custom regex or function validation.

• multiple validation with different message.

• support both RTL and LTR.

• add label and message in UX friendly format.

• customizable ui with CSS variable so you can have multiple style in different scope of your app.

• extendable so you can create your own custom input based on jb-input like jb-number-input.

• can accept persian number char and convert them to english char in value.

When to use

Use jb-input for a single-line text field that needs the JB Design System label, helper message, validation UI, form association, RTL/LTR support, or input adornment slots.

Use a more specific component when the value has a specialized format or interaction:

Use case	Prefer
Numeric value with number-specific behavior	jb-number-input
Date value	jb-date-input
Time value	jb-time-input
Mobile number	jb-mobile-input
National ID	jb-national-input
Payment card or SHABA value	jb-payment-input

Do not use jb-input for multi-line text; use jb-textarea instead.

Demo

• codepen
• storybook

Using With JS Frameworks

• 

Installation

using npm

npm i jb-input

We must import package in one of our js files.

import 'jb-input';

if you are using typescript or you need to import other modules of the component please use one nameless import and one named import(to bypass treeshake).

in your html or jsx

<jb-input label="your label" message="hint text under the text box"></jb-input>

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-input/dist/JBInput.umd.js"></script>

API reference

Use this section as a quick contract for the component. Some attributes and properties have more behavior details in their linked sections.

Attributes

name	type	default	description
value	string	""	Initial value attribute. Prefer the value property for programmatic updates.
label	string	""	Visible label text and accessible aria label.
message	string	""	Helper text shown under the input when no validation error is visible.
name	string	""	Form field name. Also forwarded to the inner native input.
type	string	browser default	Native input type. If set to number, inputmode becomes numeric when no inputmode is provided.
placeholder	string	""	Placeholder text forwarded to the inner native input.
autocomplete	string	browser default	Native autocomplete value forwarded to the inner input.
inputmode	string	browser default	Native inputmode value such as text, numeric, decimal, email, url, or search.
virtualkeyboardpolicy	string	browser default	Forwarded to the inner native input.
readonly	boolean	false	Forwarded to the inner native input.
disabled	boolean	false	Disables the input and sets the disabled custom state.
required	boolean | string	false	Enables required validation. A string value is used as the required error message.
error	string	""	External validation error message.
disable-auto-validation	boolean	false	Stops automatic validation on input and blur when set to true or an empty attribute.
size	'xs' | 'sm' | 'md' | 'lg' | 'xl'	md style defaults	Visual size variant.

Properties

name	type	readonly	description
value	string	no	Canonical value submitted with forms and returned by .value.
displayValue	string	yes	Value rendered in the inner input after standardization. It can differ from value.
initialValue	string	no	Value used as the baseline for isDirty; default is "".
validation	ValidationHelper<JBInputValue>	yes	Validation helper from jb-validation; set validation.list for custom rules.
disabled	boolean	no	Enables or disables the component.
required	boolean	no	Enables required validation.
isDirty	boolean	yes	true when current value differs from initialValue.
selectionStart	number | null	no	Forwarded to the inner input.
selectionEnd	number | null	no	Forwarded to the inner input.
selectionDirection	'forward' | 'backward' | 'none' | null	no	Forwarded to the inner input.
validationMessage	string	yes	Current native validation message from ElementInternals.

Methods

name	returns	description
checkValidity()	boolean	Runs validation without showing the error message. Dispatches invalid when invalid.
reportValidity()	boolean	Runs validation and shows the first error message. Dispatches invalid when invalid.
focus()	void	Focuses the inner native input.
setSelectionRange(start, end, direction?)	void	Forwards setSelectionRange to the inner input.
addStandardValueCallback(callback)	void	Adds a value standardization callback that can change value and displayValue.

get/set value

Like normal native input you can get/set value like below or use html attribute.

The value attribute is useful for the initial value in markup. For runtime updates, use the value property. jb-input also supports value standardization, so the visible displayValue can be different from the submitted .value.

//get value
const inputValue = document.querySelector('jb-input').value;
//set value
document.querySelector('jb-input').value = "new string";

<jb-input value="your value" />

required validation

Use required with no value for the default required message:

<jb-input label="Username" required></jb-input>

Use required="message" when the required error text must be customized:

<jb-input label="Username" required="Username is required"></jb-input>

external error

Use the error attribute when validation is controlled outside of jb-input, for example by a form library or server response. The component observes this attribute and updates its validation UI when the value changes.

<jb-input label="Username" error="This username is already taken"></jb-input>

Clear the external error by removing the attribute or setting it to an empty value.

Events

event	cancelable	when it fires	value access
input	yes	On each user edit, after value and displayValue are standardized.	event.target.value
beforeinput	yes	Before the inner input value changes. Call event.preventDefault() to block the edit.	event.target.value
change	native behavior	When the user commits the value, usually on blur.	event.target.value
keydown	yes	Re-dispatched from the inner input.	event.target.value
keyup	no	Re-dispatched from the inner input.	event.target.value
keypress	no	Re-dispatched from the inner input.	event.target.value
enter	no	On keyup when the user presses Enter.	event.target.value
invalid	no	When checkValidity() or reportValidity() finds an invalid value.	event.target.validationMessage
load	no	In connectedCallback, before init.	component instance
init	no	In connectedCallback, after initial attributes are applied.	component instance

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

input.addEventListener('input', (event) => {
  console.log(event.target.value);
});

input.addEventListener('change', (event) => {
  console.log(event.target.value);
});

input.addEventListener('enter', (event) => {
  console.log(event.target.value);
});

set validation

jb-input use jb-validation inside to handle validation. so for more information you can read jb-validation documentation.
for simple usage you can set validation to your input:

//you have 2 ways: 
//1- set list directly 
    titleInput.validation.list = [
        {
            validator: /.{3}/g,
            message: 'minimum length is 3 char'
        },
    //you can use function as a validator too
        {
            validator: ({displayValue,value})=>{return value == "hello"},
            message: 'you can only type hello'
        },
    //you can also return string in validator if you want custom error message in some edge cases
        {
            validator: ({displayValue,value})=>{
               if(value.includes("*")){
                return 'you cant write * in your text'
               }
               return true;
            },
            message: 'default error when return false'
        },
    ];
//2- pass a function that returns the validation list so on each validation process we execute your callback function and get the needed validation list
const result = document.querySelector('jb-input').validation.addValidationListGetter(getterFunction)

check validation

Like any other jb design system you can access validation by validation property:

//access validation module
document.querySelector('jb-input').validation
// check if input pass all the validations. showError is a boolean that determine your intent to show error to user on invalid status.
const result = await document.querySelector('jb-input').validation.checkValidity({showError})
//or
const result = document.querySelector('jb-input').validation.checkValiditySync({showError})
//return boolean of if inputted string is valid
const result = document.querySelector('jb-input').checkValidity()
//or return boolean and show error
const result = document.querySelector('jb-input').reportValidity()

intercept user input

I don't recommend this in most cases but sometimes you need to change what user input in the text field or prevent user from typing or paste the wrong value into the field in this scenario we have a tools to let you do this. to doing so just register a interceptor function like this:

input.addStandardValueCallback((inputtedString:string, oldValue:JBInputValue, prevResult:JBInputValue):JBInputValue=>{
    //here you can check new string, old value and  the value object that return by previous StandardValueCallback if you register multiple callback to modify value 
    return {
        // the value we return as dom.value
        value:string,
        //the value we ser into the input box that final user see
        displayValue:string
    }
});

custom inputs

if you want something more than just simple input please check this components that use jb-input but add extra validation and input check layer for better user experience:

• jb-number-input for input number
• jb-payment-input for input bank card number and SHABA number
• jb-date-input for input date value
• jb-national-input for input national ID (کد ملی) value
• jb-mobile-input for input mobile value
• jb-time-input for input time value

Slots

slot	description	example use
start-section	Content rendered before the native input.	search icon, currency prefix, country code
end-section	Content rendered after the native input.	clear button, visibility toggle, unit suffix

<jb-input label="Amount" inputmode="decimal">
  <span slot="start-section">$</span>
  <span slot="end-section">USD</span>
</jb-input>

CSS parts and states

part	description
label	The label element.
input-box	The wrapper around the slots and inner input.
input	The inner native input.
message	The helper or validation message element.

custom state	description
disabled	Applied when disabled is true.
invalid	Applied while a validation error is visible.

Accessibility notes

• The component is form-associated and submits value as its form value.
• label is exposed as the component aria label.
• message is exposed as the component aria description when no validation error is visible.
• placeholder is forwarded to the inner input and exposed as aria placeholder.
• disabled, invalid, and validation state are synchronized with ElementInternals where the browser supports it.
• The shadow root uses delegatesFocus, so focusing <jb-input> focuses the inner native input.

set custom style

you have 2 way to customize style,

1. using selectors like:states or ::part selector

jb-input::part(label){
  font-size: 2rem;
}
jb-input:states(invalid)::part(label){
  color:red;
}
jb-input:states(invalid)::part(input-box){
  border-color:red;
}
jb-input:states(disabled)::part(input){
  cursor:not-allowed;
}

we have label, input-box, input, message as a supported part in our component. you can also combine them with disabled, invalid states for different style in different states.

1. using CSS variable

CSS variable name	description
--jb-input-margin	web-component margin default is 0 0
--jb-input-border-radius	web-component border-radius default is 16px
--jb-input-border-color	border color of select in normal mode
--jb-input-border-color-focus	border color of select in normal mode
--jb-input-bgcolor	background color of input
--jb-input-border-bottom-width	border bottom thickness default is 3px
--jb-input-label-font-size	font size of input label default is 0.8em
--jb-input-label-color	change label color
--jb-input-label-margin	change label margin default is 0 4px
--jb-input-message-font-size	font size of message we show under input
--jb-input-message-color	set under box message color
--jb-input-message-error-color	change color of error we show under input
--jb-input-height	height of input default is 40px
--jb-input-placeholder-color	change placeholder color
--jb-input-placeholder-font-size	change placeholder font-size
--jb-input-value-font-size	input value font-size
--jb-input-value-color	input value color
--jb-input-input-padding	set input inner padding default is 2px 12px 0 12px
--jb-input-input-text-align	set input element text align for example if you have number Input and want to make it left
--jb-input-input-direction	set input element direction to other than inherited value from it's parent element
--jb-input-input-font-weight	set input value font-weight default is initial (browser setting)
--jb-input-box-shadow	set box shadow of input
--jb-input-box-shadow-focus	set box shadow of input on focus
--jb-input-border-width	border width default is 1px
--jb-input-label-margin	label margin default is 0
--jb-input-label-font-weight	label font weight default is 300
--jb-input-box-overflow	input box overflow default is hidden
--jb-input-bg-color-disabled	Customize bg color disabled.
--jb-input-border-bottom-width-focus	Customize border bottom width focus.
--jb-input-border-radius-lg	Customize border radius lg.
--jb-input-border-radius-sm	Customize border radius sm.
--jb-input-border-radius-xl	Customize border radius xl.
--jb-input-border-radius-xs	Customize border radius xs.
--jb-input-border-width-focus	Customize border width focus.
--jb-input-box-margin	Customize box margin.
--jb-input-height-lg	Customize height lg.
--jb-input-height-sm	Customize height sm.
--jb-input-height-xl	Customize height xl.
--jb-input-height-xs	Customize height xs.
--jb-input-input-padding-lg	Customize input padding lg.
--jb-input-input-padding-sm	Customize input padding sm.
--jb-input-input-padding-xl	Customize input padding xl.
--jb-input-input-padding-xs	Customize input padding xs.
--jb-input-label-font-size-lg	Customize label font size lg.
--jb-input-label-font-size-sm	Customize label font size sm.
--jb-input-label-font-size-xl	Customize label font size xl.
--jb-input-label-font-size-xs	Customize label font size xs.
--jb-input-message-box-display	Customize message box display.
--jb-input-message-font-size-lg	Customize message font size lg.
--jb-input-message-font-size-sm	Customize message font size sm.
--jb-input-message-font-size-xl	Customize message font size xl.
--jb-input-message-font-size-xs	Customize message font size xs.
--jb-input-value-color-disabled	Customize value color disabled.
--jb-input-value-font-size-lg	Customize value font size lg.
--jb-input-value-font-size-sm	Customize value font size sm.
--jb-input-value-font-size-xl	Customize value font size xl.
--jb-input-value-font-size-xs	Customize value font size xs.
--jb-input-width	Customize width.

Related Docs

• see jb-input/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, slots, CSS parts, and public methods.

• Import jb-input once before using <jb-input>.
• Use .value for the canonical value and .displayValue for the visible standardized value.
• Listen to input for every user edit and change for committed changes.
• Prefer the specialized JB inputs listed in When to use for formatted values.
• Set error for externally controlled validation errors; the component observes the attribute and updates its validation UI.