TextInput

07/14/21 02/26/22

Guide

NOTE: Introduced feature in v0.2.7.

TextInput is typically used for capturing string input from an end-user for input into forms, XHR requests, etc.

<script>
    import {
        Code,
        Form,
        TextInput,
    } from "@kahi-ui/framework";

    let value = "sample@sample.org";
</script>

<Form.Control logic_id="textinput-preview">
    <Form.Label>
        Register E-Mail for Newsletter
    </Form.Label>

    <TextInput bind:value />
    <Form.HelpText>
        Make sure to enter a valid E-Mail Address, e.g.
        <Code>sample@sample.org</Code>
    </Form.HelpText>
</Form.Control>

Imports

<script>
    import {TextInput} from "@kahi-ui/framework";
</script>

Maximum + Minimum

WARNING: This feature was renamed from max_length / min_length to max / min in v0.6.0 respectively.

...

TODO: snippet

Input Masking

NOTE: Introduced feature in v0.4.14.

IMPORTANT: This feature only runs on Javascript-enabled clients, you NEED to ALWAYS validate user input on the server.

You can enable input masking (dropping input that doesn't match a constraint) by enabling mask and setting the pattern properties.

NOTE: The below input is masked to hexadecimal input, e.g. abcdef1234567890

<script>
    import {TextInput} from "@kahi-ui/framework";
</script>

<TextInput pattern="[0-9a-fA-F]+" mask />

Or by implementing custom logic via the mask event.

<script>
    import {TextInput} from "@kahi-ui/framework";

    const CHARACTERS_HEXADECIMAL = new Set([
        "a",
        "b",
        "c",
        "d",
        "e",
        "f",
        "0",
        "1",
        "2",
        "3",
        "4",
        "5",
        "6",
        "7",
        "8",
        "9",
    ]);

    function on_mask(event) {
        for (const character of event.detail.value) {
            if (
                !CHARACTERS_HEXADECIMAL.has(
                    character.toLowerCase()
                )
            ) {
                event.preventDefault();
                return;
            }
        }
    }
</script>

<TextInput mask on:mask={on_mask} />

Palette

You can change the color palette of the TextInput via the palette property.

<script>
    import {
        Stack,
        TextInput,
    } from "@kahi-ui/framework";
</script>

<Stack.Container
    orientation="horizontal"
    alignment_y="top"
    spacing="medium"
    variation="wrap"
>
    <TextInput
        span_x="20"
        value="This is a DEFAULT TextInput"
    />

    <TextInput
        palette="accent"
        span_x="20"
        value="This is a ACCENT TextInput"
    />

    <TextInput
        palette="dark"
        span_x="20"
        value="This is a DARK TextInput"
    />

    <TextInput
        palette="light"
        span_x="20"
        value="This is a LIGHT TextInput"
    />

    <TextInput
        palette="alert"
        span_x="20"
        value="This is a ALERT TextInput"
    />

    <TextInput
        palette="affirmative"
        span_x="20"
        value="This is a AFFIRMATIVE TextInput"
    />

    <TextInput
        palette="negative"
        span_x="20"
        value="This is a NEGATIVE TextInput"
    />
</Stack.Container>

Block

You can alter the TextInput render as an opaque block via the variation property.

<script>
    import {
        Stack,
        TextInput,
    } from "@kahi-ui/framework";
</script>

<Stack.Container
    orientation="horizontal"
    alignment_y="top"
    spacing="medium"
    variation="wrap"
>
    <TextInput
        variation="block"
        span_x="20"
        value="This is a DEFAULT TextInput"
    />

    <TextInput
        variation="block"
        palette="accent"
        span_x="20"
        value="This is a ACCENT TextInput"
    />

    <TextInput
        variation="block"
        palette="dark"
        span_x="20"
        value="This is a DARK TextInput"
    />

    <TextInput
        variation="block"
        palette="light"
        span_x="20"
        value="This is a LIGHT TextInput"
    />

    <TextInput
        variation="block"
        palette="alert"
        span_x="20"
        value="This is a ALERT TextInput"
    />

    <TextInput
        variation="block"
        palette="affirmative"
        span_x="20"
        value="This is a AFFIRMATIVE TextInput"
    />

    <TextInput
        variation="block"
        palette="negative"
        span_x="20"
        value="This is a NEGATIVE TextInput"
    />
</Stack.Container>

Flush

NOTE: Introduced feature in v0.2.16.

You can change the appearance of the TextInput to be flush with the rest of the Application content via the variation property.

<script>
    import {TextInput} from "@kahi-ui/framework";
</script>

Input some text:
<TextInput
    variation="flush"
    span_x="20"
    value="This is a FLUSH TextInput"
/>

Sizing

WARNING: This feature was renamed from size to sizing in v0.6.0.

NOTE: By passing an array, you can set responsive values. e.g. sizing={["tiny", "tablet:medium", "mobile:medium"]}

You can change the size of the TextInput via the sizing property.

<script>
    import {
        Stack,
        TextInput,
    } from "@kahi-ui/framework";
</script>

<Stack.Container
    orientation="horizontal"
    alignment_y="top"
    spacing="medium"
    variation="wrap"
>
    <TextInput
        span_x="20"
        value="This is a DEFAULT TextInput"
    />

    <TextInput
        sizing="nano"
        span_x="20"
        value="This is a NANO TextInput"
    />

    <TextInput
        sizing="tiny"
        span_x="20"
        value="This is a TINY TextInput"
    />

    <TextInput
        sizing="small"
        span_x="20"
        value="This is a SMALL TextInput"
    />

    <TextInput
        sizing="medium"
        span_x="20"
        value="This is a MEDIUM TextInput"
    />

    <TextInput
        sizing="large"
        span_x="20"
        value="This is a LARGE TextInput"
    />

    <TextInput
        sizing="huge"
        span_x="20"
        value="This is a HUGE TextInput"
    />

    <TextInput
        sizing="massive"
        span_x="20"
        value="This is a MASSIVE TextInput"
    />
</Stack.Container>

Radius

NOTE: Introduced feature in v0.6.0.

NOTE: By passing an array, you can set responsive values. e.g. radius={["tiny", "tablet:medium", "mobile:medium"]}

You can change the border radius of the TextInput via the radius property.

<script>
    import {
        Stack,
        TextInput,
    } from "@kahi-ui/framework";
</script>

<Stack.Container
    orientation="horizontal"
    alignment_y="top"
    spacing="medium"
    variation="wrap"
>
    <TextInput
        span_x="20"
        value="This is a DEFAULT TextInput"
    />

    <TextInput
        radius="none"
        span_x="20"
        value="This is a NONE TextInput"
    />

    <TextInput
        radius="nano"
        span_x="20"
        value="This is a NANO TextInput"
    />

    <TextInput
        radius="tiny"
        span_x="20"
        value="This is a TINY TextInput"
    />

    <TextInput
        radius="small"
        span_x="20"
        value="This is a SMALL TextInput"
    />

    <TextInput
        radius="medium"
        span_x="20"
        value="This is a MEDIUM TextInput"
    />

    <TextInput
        sizing="large"
        span_x="20"
        value="This is a LARGE TextInput"
    />

    <TextInput
        radius="huge"
        span_x="20"
        value="This is a HUGE TextInput"
    />

    <TextInput
        radius="massive"
        span_x="20"
        value="This is a MASSIVE TextInput"
    />
</Stack.Container>

Shapes

NOTE: Introduced feature in v0.6.0.

NOTE: By passing an array, you can set responsive values. e.g. shape={["circle", "tablet:pill", "mobile:pill"]}

You can change the shape of the TextInput via the shape property.

<script>
    import {
        Stack,
        TextInput,
    } from "@kahi-ui/framework";
</script>

<Stack.Container
    orientation="horizontal"
    alignment_y="top"
    spacing="medium"
    variation="wrap"
>
    <TextInput
        span_x="20"
        value="This is a DEFAULT TextInput"
    />

    <TextInput
        shape="nano"
        span_x="20"
        value="This is a CIRCLE TextInput"
    />

    <TextInput
        shape="pill"
        span_x="20"
        value="This is a PILL TextInput"
    />
</Stack.Container>

Types

You can change your input type between email, password, search, text (DEFAULT), url via the type property.

<script>
    import {
        Stack,
        TextInput,
    } from "@kahi-ui/framework";
</script>

<Stack.Container
    orientation="horizontal"
    alignment_y="top"
    spacing="medium"
    variation="wrap"
>
    <TextInput
        type="email"
        span_x="20"
        value="sample@sample.org"
    />

    <TextInput
        type="password"
        span_x="20"
        value="abcdef1002"
    />

    <TextInput
        type="url"
        span_x="20"
        value="https://google.com"
    />
</Stack.Container>

TextArea

You can have the TextInput render as a <textarea> via the is property.

<script>
    import {TextInput} from "@kahi-ui/framework";
</script>

<TextInput
    is="textarea"
    value="This is a TextArea TextInput"
/>

Alignment

WARNING: This feature was renamed from align to alignment_x in v0.6.0.

You can alter the alignment of the Component via the alignment_x property.

<script>
    import {
        TextInput,
        Stack,
    } from "@kahi-ui/framework";
</script>

<Stack.Container
    orientation="horizontal"
    spacing="medium"
    variation="wrap"
>
    <TextInput value="DEFAULT TextInput" span_x="20" />

    <TextInput
        alignment_x="left"
        value="LEFT TextInput"
        span_x="20"
    />

    <TextInput
        alignment_x="center"
        value="CENTER TextInput"
        span_x="20"
    />

    <TextInput
        alignment_x="right"
        value="RIGHT TextInput"
        span_x="20"
    />

    <TextInput
        alignment_x="justify"
        value="JUSTIFY TextInput"
        span_x="20"
    />
</Stack.Container>

Placeholder

You can set the TextInput to show placeholder text whenever there is no current value.

<script>
    import {TextInput} from "@kahi-ui/framework";
</script>

<TextInput placeholder="...enter some text" />

Span X + Y

WARNING: This feature was renamed from characters / lines to span_x / span_y in v0.6.0 respectively.

You can set how wide your TextInput to an approximation of character width and new lines via the span_x and span_y properties respectively.

<script>
    import {TextInput} from "@kahi-ui/framework";
</script>

<TextInput
    value="This input should be about 4 characters wide."
    span_x="4"
/>

<TextInput
    is="textarea"
    value="This input should be about 3 lines tall."
    span_y="3"
/>

Resizable TextArea

You alter the a <textarea> based TextInput to resizable both axis true, horizontally x, or vertically y via the resizable property.

<script>
    import {TextInput} from "@kahi-ui/framework";
</script>

<TextInput
    is="textarea"
    value="This is a resizable TextArea"
    resizable
/>

API Reference

Properties

`TextInput`

Name	Description	Types
`is`	Changes the HTML tag used for rendering the TextInput.	`input (DEFAULT)textarea`
`type`	Sets which type of text is being accepted.	`emailpasswordsearchtext (DEFAULT)url`
`palette`	Alters the displayed color scheme.	`autoinverseinheritaccentneutraloffdarklightalertaffirmativeinformativenegative`
`radius`	Changes the border radius of the TextInput.	`none (DEFAULT)nanotinysmallmediumlargehugemassive{VIEWPORT}:{RADIUS}`
`shape`	Changes the shape of the TextInput.	`circlepill{VIEWPORT}:{SHAPE}`
`sizing`	Renders the TextInput at a different sizes.	`nanotinysmallmediumlargehugemassive{VIEWPORT}:{SIZING}`
`variation`	Alters the rendered appearance of the TextInput.	`blockflush`
`disabled`	Renders the TextInput with disabled attribute, and styles the TextInput partially transparent.	`boolean`
`required`	Sets if the TextInput should be required, which will fail submission on a if missing.	`boolean`
`readonly`	Sets if the TextInput should be readonly, which will prevent further edits.	`boolean`
`name`	Sets the form name of the TextInput.	`string`
`max`	Sets the maximum amount of characters that the end-user CAN input, which will fail submission on a if the input is invalid.	`numberstring`
`min`	Sets the minimum amount of characters that the end-user MUST input, which will fail submission on a if the input is invalid.	`numberstring`
`mask`	Enables user input masking dropping characters that aren't validated by the pattern property or mask event.	`string`
`pattern`	Sets a validation Regular Expression on TextInput, which will fail submission on a if the input is invalid.	`RegExpstring`
`placeholder`	Sets the text that is rendered if there is no current value.	`string`
`value`	Sets the text value of the TextInput.	`string`
`characters`	Sets the width of the TextInput to an approximation of the amount of characters to display.	`numberstring`
`lines`	(TEXTAREA ONLY) Sets the height of the TextInput to an approximation of the amount of text lines to display.	`numberstring`
`resizable`	(TEXTAREA ONLY) Sets if the TextArea should be resizable by the end-user.	`booleanxy`
`spell_check`	(TEXTAREA ONLY) Sets if Browser spellcheck should be enabled. Allows the Browser to automatically determine this, if unset.	`boolean`

Events

`TextInput`

Name	Description	Types
`change`	Fires whenever the TextInput loses focus and its value was changed.	`InputEvent`
`input`	Fires whenever the TextInput has its value changed.	`InputEvent`
`mask`	Fires whenever the TextInput is receiving input and the mask property is set to true.	`CustomEvent<{value: string}>`