Input
This component was previously named ds-text-input.
Options
There are two basic html structures for using ds-input. The most basic implementation is to apply ds-input directly to the html input/textarea element.
As of v1.13 ds-input can be applied to a wrapper div which provides better icon support and improved layout when combined with ds-text --addon.
ds-input may be used with html input or html textarea (available from v1.8.12+) elements.
Basic usage
Component state
Disabled
Use the native disabled attribute for form controls. The --disabled modifier applies the disabled appearance and prevents pointer interaction, but does not provide native disabled semantics by itself.
Readonly
Placeholder
Required
Use the native required attribute and identify the requirement in the field label. See Required fields for the complete pattern.
Visual states
Text input adheres to the 4x preset visual states - alert, warning, success and info.
Icons
To apply icons to ds-input, you must use the div based html structure.
Size
Small, large
Narrow, mid, wide, extra-wide
By default ds-input takes the full width of it’s container element.
Full width
--full-width and its alias --full make the input fill the available width and allow it to grow within a flex layout.
Types
Date picker
The native date picker works across all target browsers and the UI is specific to each to browser.
The displayed date is formatted based on the locale of the user’s browser, but the parsed value is always formatted yyyy-mm-dd
Optional attributes
| Attribute | Required | Description | Value |
|---|---|---|---|
max |
Optional | The latest allowable date | yyyy-mm-dd |
min |
Optional | The earliest allowable date | yyyy-mm-dd |
step |
Optional | The step increment when adjusting the date | “any” or number |
Time picker
The native time picker works across all target browsers and the UI is specific to each to browser.
The displayed time is formatted based on the locale of the user’s browser, but the parsed value is always in 24-hour format that includes leading zeros: hh:mm or hh:mm:ss.
The time picker is only for specific time values (00:00 - 24:00). Longer times (for specifying time length such as 48 hours) will not work with the native type="time" component.
Optional attributes
| Attribute | Required | Description | Value |
|---|---|---|---|
max |
Optional | The latest allowable time | hh:mm or hh:mm:ss |
min |
Optional | The earliest allowable time | hh:mm or hh:mm:ss |
step |
Optional | The step increment when adjusting the time | “any” or number |
Datetime picker
The native datetime picker UI is provided by the browser and operating system. Apply the --date variant to a wrapper containing an input with type="datetime-local".
See also the split datetime picker when the date and time need to be separate controls.
The displayed date is formatted based on the locale of the user’s browser, but the parsed value is always formatted yyyy-mm-ddThh:mm
Optional attributes
| Attribute | Required | Description | Value |
|---|---|---|---|
max |
Optional | The latest allowable date | yyyy-mm-ddThh:mm |
min |
Optional | The earliest allowable date | yyyy-mm-ddThh:mm |
step |
Optional | The step increment when adjusting the date | “any” or number |
pattern |
Optional | Only used by browsers that don’t support datetime-local | “[0-9]4-[0-9]2-[0-9]2T[0-9]2:[0-9]2” |
placeholder |
Optional | Only used by browsers that don’t support datetime-local | “yy-mm-ddThh:mm” |
Split datetime
Split datetime uses two input fields - type="date", type="time" (See the requirements/options for each above) and optional ds-button.
This version has the advantage of working across all target browsers (including Firefox).
File upload
See Field with file upload for additional examples.
Color picker
Use the --color-picker variant on a wrapper containing a native color input. The optional __label, __swatch, and __value children present the current selection; application code must keep the swatch and value text synchronized when the input changes.
Styles
Text style
The --text variant removes the input border and background so the control appears as plain text.
Copy
The --copy variant selects the control’s content and positions an accompanying copy button. Clipboard behavior requires JavaScript. See the Copy pattern for complete examples.
Resize
Textareas resize vertically by default. Use a resize modifier to select another behavior.
| Modifier | Behavior |
|---|---|
--resize-horizontal |
Resize horizontally |
--resize-vertical |
Resize vertically |
--resize |
Resize horizontally and vertically |
--resize-none, --no-resize |
Disable manual resizing |
Auto-sizing
The --auto-sizing modifier allows a textarea to grow with its content.
Indent and gap
ds-input supports the global indent modifiers (--indent-*, --v-indent-*, --h-indent-*, and their --no-* variants) and gap modifiers (--gap-*, --v-gap-*, --h-gap-*, and their --no-* variants). Indent controls the input padding; gap controls spacing between direct children of the wrapper form.
CSS custom properties
The following custom properties can be set with CSS, a style attribute, or JavaScript.
| Property | Default | Description |
|---|---|---|
--ds-input-width |
100% |
Width of the input and its wrapper |
--ds-input-height |
40px |
Height of the input control and its wrapper |
--ds-input-text-color |
var(--color-default) |
Text color for the input control |
--ds-input-background-color |
var(--color-background) |
Background color for the input control |
--ds-input-indent |
10px |
Base padding for the input control |
--ds-input-v-indent |
var(--ds-input-indent) |
Vertical padding for the input control |
--ds-input-h-indent |
var(--ds-input-indent) |
Horizontal padding for the input control |
--ds-input-gap |
var(--space-xsmall) |
Base gap between input children |
--ds-input-v-gap |
var(--ds-input-gap) |
Vertical gap between input children |
--ds-input-h-gap |
var(--ds-input-gap) |
Horizontal gap between input children |
--ds-input-border-radius |
var(--radius-small) |
Border radius for the input and its wrapper |
--ds-input-border-top-left-radius |
var(--ds-input-border-radius) |
Top-left border radius for the input and its wrapper |
--ds-input-border-top-right-radius |
var(--ds-input-border-radius) |
Top-right border radius for the input and its wrapper |
--ds-input-border-bottom-right-radius |
var(--ds-input-border-radius) |
Bottom-right border radius for the input and its wrapper |
--ds-input-border-bottom-left-radius |
var(--ds-input-border-radius) |
Bottom-left border radius for the input and its wrapper |
--ds-input-border-width |
1px |
Border width for the input and its wrapper |
--ds-input-border-color |
var(--color-default-light) |
Border color for the input and its wrapper |
Composition
Child components
The wrapper form of ds-input supports SDS components as direct children before or after the native input element.
Buttons
ds-button can be used as a child of ds-input. See ds-button for further examples.
Text
ds-text can be used as a child of ds-input. See ds-text for further examples.
Inline icons
Tags
Multiple child components
Examples
datetime-split combined with sizing options
datetime-split with buttons combined with sizing options
datetime-split with ds-autoselect combined with sizing options
datetime-split with buttons and ds-autoselect combined with sizing options
Manifest
The component manifest describes this component's API: its modifiers, structure, data attributes, CSS custom properties, accessibility notes, and example markup. It is consumed by tooling such as AI assistants and code generators.
Latest version: https://assets.soracom.io/sds/3.41.0/ds-input/manifest.json?v=3.41.0