Input<mds-input>Generato da @maggioli-design-system/magma@2.3.0dist/documentation.json. Incapsulamento: shadow.
Questa pagina è generata dai pacchetti Magma, documentati solo in inglese.
Il primo esempio della pagina Pattern, dal vivo. Cambia le sue proprietà qui sotto e l'anteprima le segue; Ripristina riporta l'esempio com'era.
Proprietà
autocompleteenumSpecifies whether the element should have autocomplete enabled
controlsIconenumSpecifies the icon type of the counter button when the input type is set to number
controlsLayoutenumSpecifies the layout of the counter button when the input type is set to number
sizeenumSpecifies the height of the field, the same as mds-button: sm 28px, md 36px, lg 48px. A textarea keeps its own height (--mds-input-textarea-min-height)
typeenumSpecifies the type of input element
typographyenumSpecifies the typography of input element
variantenumSets the variant of the input field
autofocusautofocusbooleanSpecifies that the element should automatically get focus when the page loads
awaitawaitbooleanSpecifies if the spinner icon is shown, replacing the icon if present
disableddisabledbooleanIf true, the element is displayed as disabled
micmicbooleanToggles text recognition
readonlyreadonlybooleanSpecifies that the element is read-only
requiredrequiredbooleanSpecifies that the element must be filled out before submitting the form
accessibleNamestringThe accessible name of the native control: the label a screen reader announces. An mds-input-field around the component passes its own label down here, so the attribute is only written by hand when the input stands on its own. The placeholder is deliberately not a fallback: it disappears as soon as the field is filled.
iconstringAn icon displayed at the right of the input
maxstringSpecifies the maximum value use it with input type="number" or type="date" Example: max="180", max="2046-12-04"
minstringSpecifies the minimum value use it with input type="number" or type="date" Example: min="-3", min="1988-04-15"
namestringIs needed to reference the form data after the form is submitted
patternstringSpecifies a regular expression the whole value has to match, as the pattern attribute of a native input: a value that does not match stops the submit of the form
placeholderstringSpecifies a short hint that describes the expected value of the element
stepstringSpecifies the interval between legal numbers in an input field
tipstringSets the word(s) of the tip of the input field
valuestringSpecifies the value of the input element
maxlengthnumberSpecifies the maximum number of characters allowed in an element. Use it with input type="text". If maxlength is set to 0 or a negative number it will be considered as undefined.
minlengthnumberSpecifies the minimum number of characters allowed in an element use it with input type="number"
Panoramica
The <mds-input> web component is the primary single- and multi-line text entry control of the Magma Design System. It wraps a native <input> (or <textarea> when type="textarea") and layers on form association, validation, inline tips, iconography, password masking, numeric steppers, datalist suggestions and speech-to-text dictation.
Semantic Behavior
Form association: The component reports its value to the surrounding <form>, so it submits natively. On disabled the reported value is cleared. A form reset brings back the value the field had at load, both shown and submitted, and drops the 'success' or 'error' look of a past blur, like a native input.Disabled fieldset: A disabled <fieldset> around the component disables it as disabled does, like a native control: it cannot be changed and its value is left out of the form, until the fieldset is enabled.Form validity: The validators below also decide the validity reported to the form, on every change of the value or of the rules: like a native control, an invalid field matches :invalid and stops the submit, the browser shows a message in the page language next to the field and focuses it, and the field switches to 'error' as on blur. Disabled and read-only fields are left out, and novalidate on the <form> turns the check off. type="email" and type="url" check the format of the value as a native input does.Validation on blur: Validation runs when the field loses focus (and re-runs on input once invalid). It drives the variant automatically to 'success' or 'error', emits mdsInputValidation with the boolean result, and reverts to 'primary' when an optional field is emptied.Type-aware validators: The active validator set is derived from type - email and url install the format validators of the native types, cf the codice fiscale format and length validators, isbn a checksum validator, piva the partita IVA one (11 digits, the last one the check digit) and cc the card number one (13 to 19 digits, in groups split by spaces or dashes, that pass the Luhn check); no type applies an input mask, while required, min/max (any number, 0 included), minlength/maxlength and pattern add the corresponding constraint validators. As on a native input, pattern has to match the whole value, an expression that does not compile sets no rule, and number, date, time and textarea ignore it. The set is rebuilt whenever one of these props changes, also after load, as with the React wrappers under SSR: a pristine field only updates its required tip, a field already validated on blur is validated again. Custom validators can be attached at runtime through the addValidator/removeValidator/hasValidator/getErrors methods.Disabled / read-only tips: disabled and readonly surface a persistent top tip describing the state; read-only fields also auto-select their text on focus.Character counter: When maxlength is set a bottom counter tip shows current / max and shifts through fullness variants as the value approaches the limit. A maxlength of 0 or less is treated as unset.Password masking: With type="password" a toggle button reveals/hides the value; it is disabled with the field.Number steppers: With type="number" increment/decrement buttons are rendered; their placement follows controlsLayout and their glyphs follow controlsIcon. They are disabled on a disabled or read-only field, like the spin buttons of a native one.Speech-to-text: When mic is set a dictation button transcribes speech into the value, replacing what was there, and emits mdsInputSpeechEnd when the user stops the dictation; when the Web Speech API is unavailable the button switches to an error state and the value is left as it is. The dictation button is disabled on a disabled or read-only field, which the user cannot change, and a dictation in progress stops, emitting mdsInputSpeechEnd, when the field becomes so.Emitted events: mdsInputChange carries the new value, mdsInputKeydown fires on every key pressed in the field with the native KeyboardEvent as detail (before the value changes: read the value from mdsInputChange), and mdsInputFocus/mdsInputBlur fire on focus transitions.
Properties & Visual Configurations
The shared variant ladder (color role) is defined in agents/variants.md; <mds-input> consumes it for both intent styling and validation feedback, but does not expose a tone prop. It accepts primary (default), ai, info, success, warning and error.type selects both the rendered control and the validation profile: it covers the native HTML types plus format types ('cf', 'piva', 'isbn', 'cc') and switches the host to a multi-line <textarea> for 'textarea'.variant="ai" auto-assigns the AI chatbot icon when no icon is otherwise provided, signposting AI-assisted fields.size sets the height of the field, the same as <mds-button>: sm 28px, md 36px, lg 48px (default). Match it to the buttons next to the field, or go smaller in dense layouts (filter bars, table toolbars); the text style stays the same, the padding and the inner icon, stepper buttons and password and microphone toggles scale with it. A textarea keeps its own height (--mds-input-textarea-min-height).
Other behavioral props
icon is an SVG filename slug from the Magma icon library shown at the leading (left) edge of the field; it is suppressed while await is active, since the spinner takes its place.controlsLayout chooses between stacked ('vertical') and split ('horizontal') stepper buttons, and controlsIcon picks arrow vs. plus/minus glyphs - both apply only to type="number".datalist supplies suggestion options for type="search" style autocompletion.tip renders inline helper text below the field, and typography selects the field’s text scale.