TextInput

Use a TypeScript application with a CSS-capable bundler. Install @blukavantui/community@1.1.0 from npm, or install the matching downloaded archive.

// In your test application’s package.json dependencies:
"@blukavantui/community": "1.1.0"

Run npm install in that test application to install the component package. Load the theme once and the component stylesheet shown in the adapter. Create an empty host in your view:

<div id="example"></div>

This reusable adapter follows the Button and TimePicker guide pattern. Its types come from the factory, so required options stay required. Attach the host first; mount once per view and retain the handle.

import { createTextInput } from '@blukavantui/community/text-input'
import '@blukavantui/community/theme.css'
import '@blukavantui/community/text-input.css'

type Options = NonNullable<Parameters<typeof createTextInput>[1]>
type Events = NonNullable<Parameters<typeof createTextInput>[2]>

export function mount(host: HTMLElement, options: Options, events: Events = {}) {
  const instance = createTextInput(host, options, events)
  return { instance, update: (patch: Partial<Options>) => instance.update(patch), destroy: () => instance.destroy() }
}

User interaction calls Change; update() and reset() do not. Synchronize your application state after either method. Clear a stale Error before validate(), and validate again in your application before saving. These fields expose Change and Blur; TextInput also exposes Action.

The working example stores values in application variables. If the host is inside a form, a non-canceled form reset restores initial component values; synchronize your store after that reset and clear any application errors explicitly.

Use: Leading, Trailing, Action

Use typed adornment objects for text prefixes, symbols, images and buttons. Supply a real application image URL and useful Alt text; action buttons receive a stable Key and accessible Label. Changing adornments does not require recreating the input.

Use: Value, Type, Clearable, Error, Blur

Keep application state in Change. On blur, clear a stale Error before validate(). Clearable emits an empty string. Use Type password with RevealPassword for password visibility; never put real credentials in a playground.

Save this as text-input.ts, import its mount function and pass your attached host. It includes application state, interactive controls and a destroy handler. Pass your image URL as the second argument to show an image on the left; the example includes an action button on the right.

Download the editable TypeScript example ↓

import { createTextInput } from '@blukavantui/community/text-input'
import '@blukavantui/community/theme.css'
import '@blukavantui/community/text-input.css'

// Pass a public application image URL for the left-side image example.
export function mount(host: HTMLElement, imageUrl?: string) {
  const root = document.createElement('section')
  const target = document.createElement('div')
  const status = document.createElement('p')
  status.setAttribute('role', 'status')
  const reset = document.createElement('button')
  reset.type = 'button'; reset.textContent = 'Reset email'
  root.append(target, status, reset); host.append(root)
  let email = ''
  const instance = createTextInput(target, {
    Name: 'email', Label: 'Contact email', Type: 'email', Required: true,
    Value: email, Autocomplete: 'email', Clearable: true,
    Leading: imageUrl ? { Kind: 'Image', Src: imageUrl, Alt: 'Contact' }
      : { Kind: 'Icon', Text: '@', Label: 'Email' },
    Trailing: { Kind: 'Action', Text: 'Check', Label: 'Check this email', Key: 'check' },
  }, {
    Change(value) { email = value; instance.update({ Error: '' }); status.textContent = `Draft: ${email || '(empty)'}` },
    Action(key, value) {
      if (key !== 'check') return
      instance.update({ Error: '' })
      const valid = instance.validate()
      instance.update({ Error: valid ? '' : 'Enter a valid contact email.' })
      status.textContent = valid ? `Ready to use: ${value}` : 'Please correct the email.'
      // A format check is not verification that an address exists.
    },
    Blur() { email = instance.getValue() },
  })
  const listeners = new AbortController()
  reset.addEventListener('click', () => {
    instance.update({ Error: '' }); instance.reset()
    email = instance.getValue(); status.textContent = 'Email reset.'
  }, { signal: listeners.signal })
  return { instance, destroy() { listeners.abort(); instance.destroy(); root.remove() } }
}

• Use Tab to reach the control. Space toggles choices; radio groups support arrow navigation. Inputs retain standard text-editing shortcuts.
• Check required, disabled and read-only states; verify reset and programmatic updates also synchronize your application state.
• Call the example handle’s destroy() when the view is removed. Abort your application listeners and requests; ignore any asynchronous result after disposal.
• Mount again and confirm there is one instance and one callback per interaction.

In Manage Dependencies, select TextInput from BluKavantUi_Community_Inputs, together with the structures and public actions used by its API. Refresh existing references before publishing your consumer. Inherit the shared Community theme in your application's theme.

ExampleScreen — Screen (your application)
└─ ExistingLayout — referenced Layout Block instance (child of ExampleScreen)
   └─ Content — existing slot on ExistingLayout
      └─ ComponentRegion — Container (child of that slot)
         └─ MainComponent — BluKavantUi_Community_Inputs.TextInput Block instance (child of ComponentRegion)

Reuse your screen’s existing Layout and its content slot; do not add a second layout. If your Layout names that slot differently, use its actual content slot. ComponentRegion is a new Container; MainComponent is a referenced Block instance.

Create local variables on ExampleScreen for the values your application changes. Use the exact native types below; lists are typed OutSystems Lists, while inputs ending in Json are Text containing the documented JSON. Bind each MainComponent.Input to its matching StateInput local. Constants can instead use the default directly. Fill required data from your Aggregate or Data Action before enabling interaction.

For each event you use, create the named screen Client Action below. Add its listed input parameters with the exact types. Select that action on MainComponent's event property, then enter each mapping explicitly. Event arguments and screen locals are different scopes.

Inputs ending in Json are Text containing JSON. Define the matching application Structure/List, then use JSON Serialize. The JSON below is payload content, not an OutSystems expression literal.

{
  "Kind": "Image",
  "Src": "/images/account.svg",
  "Alt": "Account"
}

[
  {
    "Kind": "Text",
    "Text": "USD"
  },
  {
    "Kind": "Icon",
    "Text": "✓",
    "Label": "Verified"
  },
  {
    "Kind": "Action",
    "Text": "Find",
    "Label": "Find account",
    "Key": "find"
  }
]

For runtime images, bind LeadingImageUrl / LeadingImageAlt or TrailingImageUrl / TrailingImageAlt. Each side uses image URL first, then Text, then Json. Use the Json input for an Action adornment and map OnAction.Key and Value to your screen handler.

For images visible while designing, reference InputGroup from the same Inputs producer. Place actual Image widgets in its Leading and/or Trailing slots, and the TextInput in Control. Keep the accessible label on the inner TextInput using its Label input. Use FormField separately only when you can provide the actual focusable control id; a referenced Block id identifies its wrapper.

ExampleScreen → ExistingLayout.Content
└─ InputGroup (referenced Block)
   ├─ Leading → Image (application resource, descriptive alt text)
   ├─ Control → TextInput (Value = StateValue)
   └─ Trailing → Image (application resource, decorative alt text if appropriate)

Dynamic TextInput image URL inputs resolve at runtime; they can appear as expressions on the Service Studio canvas. InputGroup contains actual editable slots for the image widgets.

These custom controls do not automatically participate in OutSystems Form.Valid. Validate your bound screen state, assign Error text for invalid fields, and call your own Server Action only when valid. Validate again on the server. Required is a runtime field requirement, not a mandatory Block input.

Publish the consumer, supply representative data, trigger each connected event and inspect the mapped arguments. Check a failed request, a retry and leaving/reopening the screen. The table describes the native contract; the Web recipes can contain capabilities with different native names or availability. Use these native names and the API tab as the authority for Service Studio.