Blazorise On-screen Keyboard

The on-screen keyboard lets text-capable input components show a virtual keyboard when they receive focus.

Add the <OnScreenKeyboardProvider> once near the root of your app, then enable the keyboard on the inputs that need it with the OnScreenKeyboard parameter.

Provider setup

The provider renders the keyboard and connects it to focused input components.

<ThemeProvider Theme="@theme">
    <Router AppAssembly="@typeof( App ).Assembly" />
    <OnScreenKeyboardProvider />
</ThemeProvider>

Examples

Text input

Enable the keyboard on a single <TextInput> by setting OnScreenKeyboard.

Text input

<Field>
    <FieldLabel>Text input</FieldLabel>
    <TextInput @bind-Value="@textValue" Placeholder="Focus to show the keyboard" OnScreenKeyboard />
</Field>

@code {
    private string textValue;
}

Button trigger

Show the keyboard programmatically from a custom trigger. This example uses an addon button next to the input.

Button trigger

<Field>
    <FieldLabel>Button trigger</FieldLabel>
    <Addons>
        <Addon AddonType="AddonType.Body">
            <TextInput @ref="@textInputRef" @bind-Value="@textValue" Placeholder="Click the keyboard button" OnScreenKeyboard OnScreenKeyboardShowMode="OnScreenKeyboardShowMode.Manual" />
        </Addon>
        <Addon AddonType="AddonType.End">
            <Button Color="Color.Secondary" Clicked="@ShowKeyboard">Keyboard</Button>
        </Addon>
    </Addons>
</Field>

@code {
    private TextInput textInputRef;
    private string textValue;

    private Task ShowKeyboard()
    {
        return textInputRef?.ShowOnScreenKeyboard() ?? Task.CompletedTask;
    }
}

Memo input

Multiline inputs insert a new line by default. Set OnScreenKeyboardEnterKeyBehavior to Submit when the enter key should submit the nearest validations or form.

Memo input

<Field>
    <FieldLabel>Memo input</FieldLabel>
    <MemoInput @bind-Value="@memoValue" Placeholder="Focus to enter multiple lines" OnScreenKeyboard="true" />
</Field>

@code {
    private string memoValue;
}

Input-specific layouts

Text roles and numeric inputs choose a suitable layout automatically. You can also set OnScreenKeyboardLayout explicitly.

Email layout

Numeric layout

Explicit layout

<Fields>
    <Field ColumnSize="ColumnSize.Is4.OnDesktop">
        <FieldLabel>Email layout</FieldLabel>
        <TextInput @bind-Value="@emailValue" Placeholder="name@example.com" Role="TextRole.Email" OnScreenKeyboard="true" />
    </Field>
    <Field ColumnSize="ColumnSize.Is4.OnDesktop">
        <FieldLabel>Numeric layout</FieldLabel>
        <NumericInput TValue="int?" @bind-Value="@numberValue" Placeholder="123" OnScreenKeyboard="true" />
    </Field>
    <Field ColumnSize="ColumnSize.Is4.OnDesktop">
        <FieldLabel>Explicit layout</FieldLabel>
        <TextInput @bind-Value="@urlValue" Placeholder="https://example.com" OnScreenKeyboard="true" OnScreenKeyboardLayout="OnScreenKeyboardLayout.Url" />
    </Field>
</Fields>

@code {
    private string emailValue;

    private int? numberValue;

    private string urlValue;
}

Special characters

Enable ShowSpecialCharactersKey to add a toggle key for symbols and punctuation to text-based keyboard layouts.

<ThemeProvider Theme="@theme">
    <Router AppAssembly="@typeof( App ).Assembly" />
    <OnScreenKeyboardProvider ShowSpecialCharactersKey />
</ThemeProvider>

Custom layouts

Use SpecialCharactersRows or LayoutProvider when the built-in rows are not enough for the target input.

@code {
    private IReadOnlyList<IReadOnlyList<OnScreenKeyboardKey>> SpecialCharactersRows = new List<IReadOnlyList<OnScreenKeyboardKey>>
    {
        new[] { new OnScreenKeyboardKey( "1" ), new OnScreenKeyboardKey( "2" ), new OnScreenKeyboardKey( "3" ) },
        new[] { new OnScreenKeyboardKey( "!" ), new OnScreenKeyboardKey( "?" ), new OnScreenKeyboardKey( "." ) },
        new[] { new OnScreenKeyboardKey( OnScreenKeyboardKeyType.SpecialCharacters, "ABC" ) },
    };
}

<OnScreenKeyboardProvider ShowSpecialCharactersKey
                          SpecialCharactersRows="@SpecialCharactersRows" />

Keyboard size and layout

Use KeyboardSize to constrain the keyboard width, and KeyLayout to center fixed-width keys instead of stretching them across each row.

<ThemeProvider Theme="@theme">
    <Router AppAssembly="@typeof( App ).Assembly" />
    <OnScreenKeyboardProvider KeyboardSize="OnScreenKeyboardSize.Large"
                              KeyLayout="OnScreenKeyboardKeyLayout.Centered" />
</ThemeProvider>

Key template

Use KeyTemplate to customize the content rendered inside each key while keeping the default keyboard behavior.

<OnScreenKeyboardProvider KeyboardSize="OnScreenKeyboardSize.Large"
                          KeyLayout="OnScreenKeyboardKeyLayout.Centered">
    <KeyTemplate Context="key">
        @if ( key.Key.KeyType == OnScreenKeyboardKeyType.Shift )
        {
            <Icon Name="IconName.ArrowUp" />
        }
        else if ( key.Key.KeyType == OnScreenKeyboardKeyType.Backspace )
        {
            <Icon Name="IconName.Backspace" />
        }
        else if ( key.Key.KeyType == OnScreenKeyboardKeyType.Clear )
        {
            <Icon Name="IconName.Clear" />
        }
        else
        {
            @key.DisplayText
        }
    </KeyTemplate>
</OnScreenKeyboardProvider>

Global option

If the keyboard should be available globally, enable it in Blazorise options. By default, global enablement targets text and numeric inputs only. Use OnScreenKeyboardInputType to opt date, time, and picker inputs into the global keyboard behavior.

builder.Services
    .AddBlazorise( options =>
    {
        options.AccessibilityOptions.OnScreenKeyboard.Enabled = true;
        options.AccessibilityOptions.OnScreenKeyboard.InputTypes =
            OnScreenKeyboardInputType.Text
            | OnScreenKeyboardInputType.Numeric
            | OnScreenKeyboardInputType.Date
            | OnScreenKeyboardInputType.Time
            | OnScreenKeyboardInputType.Pickers;
        options.AccessibilityOptions.OnScreenKeyboard.EnterKeyBehavior = OnScreenKeyboardEnterKeyBehavior.Submit;
        options.AccessibilityOptions.OnScreenKeyboard.KeyboardSize = OnScreenKeyboardSize.Large;
        options.AccessibilityOptions.OnScreenKeyboard.KeyLayout = OnScreenKeyboardKeyLayout.Centered;
        options.AccessibilityOptions.OnScreenKeyboard.KeyWidth = 72;
        options.AccessibilityOptions.OnScreenKeyboard.KeyMinHeight = 56;
    } );

API

Parameters

OnScreenKeyboardProvider

Parameter	Description	Type	Default
`AriaLabel`	Gets or sets the keyboard aria-label.	`string`	`"On-screen keyboard"`
`ChildContent`	Gets or sets custom keyboard content.	`RenderFragment`	`null`
`KeyboardSize`	Gets or sets the keyboard visual width.	`OnScreenKeyboardSize?`	`null`
`KeyColor`	Gets or sets the button color.	`Color`	`Color.Secondary`
`KeyLayout`	Gets or sets the key arrangement inside keyboard rows.	`OnScreenKeyboardKeyLayout?`	`null`
`KeyMinHeight`	Gets or sets the key minimum height, in pixels.	`int?`	`null`
`KeyOutline`	Gets or sets whether key buttons should be outlined.	`bool`	`true`
`KeySize`	Gets or sets the button size. Possible values:`Default`, `ExtraSmall`, `Small`, `Medium`, `Large`, `ExtraLarge`	`Size`	`Size.Default`
`KeyTabIndex`	Gets or sets the tab index for rendered key buttons.	`int?`	`-1`
`KeyTemplate`	Gets or sets the template used to render each keyboard key content.	`RenderFragment<OnScreenKeyboardKeyContext>`	`null`
`KeyWidth`	Gets or sets the base key width, in pixels, used by centered key layout.	`int?`	`null`
`Placement`	Gets or sets the keyboard placement.	`OnScreenKeyboardPlacement?`	`null`
`ShowSpecialCharactersKey`	Gets or sets whether text keyboards should show a key that toggles special characters.	`bool`	`false`
`SpecialCharactersRows`	Gets or sets the rows used when the special characters keyboard is active.	`IReadOnlyList<IReadOnlyList<OnScreenKeyboardKey>>`	`null`
`ZIndex`	Gets or sets the CSS z-index used by the fixed keyboard placement. When not set, the current style provider default is used.	`int?`	`null`

BaseOnScreenKeyboardInputComponent

Parameter	Description	Type	Default
`AriaDescribedBy`	Specifies the aria-describedby attribute value. Remarks When set, this value is rendered as-is and overrides help and validation message ids generated by Field and Validation.	`string`
`AriaInvalid`	Specifies the aria-invalid attribute value. Remarks When set, this value is rendered as-is and overrides the validation-derived aria-invalid state.	`string`
`AriaLabelledBy`	Specifies the aria-labelledby attribute value. Remarks When set, this value is rendered as-is. Some non-labelable controls can otherwise derive it automatically from a parent FieldLabel or FieldsLabel.	`string`
`AriaRequired`	Specifies the aria-required attribute value. Remarks When set, this value overrides the required-field state resolved from the parent Validation.	`bool`	`false`
`Autofocus`	Set's the focus to the component after the rendering is done.	`bool`	`false`
`ChildContent`	Specifies the content to be rendered inside this BaseOnScreenKeyboardInputComponent.	`RenderFragment`	`null`
`Disabled`	Add the disabled boolean attribute on an input to prevent user interactions and make it appear lighter.	`bool`	`false`
`Feedback`	Placeholder for validation messages.	`RenderFragment`	`null`
`OnScreenKeyboard`	Enables the on-screen keyboard for this input component. When not explicitly set, the global accessibility option is used.	`bool`	`false`
`OnScreenKeyboardEnterKeyBehavior`	Specifies how the on-screen keyboard enter key should behave for this input component. Possible values:`Default`, `NewLine`, `Submit`, `Hide`, `KeyDown`	`OnScreenKeyboardEnterKeyBehavior`	`OnScreenKeyboardEnterKeyBehavior.Default`
`OnScreenKeyboardLayout`	Specifies the on-screen keyboard layout for this input component. When not explicitly set, the global accessibility option is used. Possible values:`Text`, `Numeric`, `Decimal`, `Email`, `Url`, `Telephone`	`OnScreenKeyboardLayout`	`OnScreenKeyboardLayout.Text`
`OnScreenKeyboardShowMode`	Gets or sets how the on-screen keyboard is shown for this input. Possible values:`Default`, `Focus`, `Manual`	`OnScreenKeyboardShowMode`	`OnScreenKeyboardShowMode.Default`
`ReadOnly`	Add the readonly boolean attribute on an input to prevent modification of the input’s value.	`bool`	`false`
`Size`	Sets the size of the input control.	`Size?`	`null`
`TabIndex`	If defined, indicates that its element can be focused and can participates in sequential keyboard navigation.	`int?`	`null`
`Value`	Specifies the value inside the input field.	`TValue`	`null`
`ValueExpression`	Specifies an expression that identifies the input value.	`Expression<Func<TValue>>`	`null`

BlazoriseOnScreenKeyboardOptions

Parameter	Description	Type	Default
`AutoScroll`	If true, the focused input is scrolled into view when it would be covered by the on-screen keyboard.	`bool`	`true`
`AutoScrollMargin`	Gets or sets the viewport margin, in pixels, kept between the focused input and the on-screen keyboard during automatic scrolling.	`int`	`12`
`DefaultLayout`	Gets or sets the default keyboard layout. When not set, each input component chooses its own layout.	`OnScreenKeyboardLayout?`	`null`
`Enabled`	If true, input components can show the on-screen keyboard when they receive focus.	`bool`	`false`
`EnterKeyBehavior`	Gets or sets how the on-screen keyboard enter key should behave. Possible values:`Default`, `NewLine`, `Submit`, `Hide`, `KeyDown`	`OnScreenKeyboardEnterKeyBehavior`	`OnScreenKeyboardEnterKeyBehavior.Default`
`HideOnBlur`	If true, the on-screen keyboard is hidden when the active input loses focus.	`bool`	`true`
`HideOnEnter`	If true, the on-screen keyboard is hidden when the enter key is pressed.	`bool`	`true`
`InputTypes`	Gets or sets the input types enabled by the global on-screen keyboard option. Possible values:`None`, `Text`, `Numeric`, `Date`, `Time`, `Pickers`, `All`	`OnScreenKeyboardInputType`	`OnScreenKeyboardInputType.Text \| OnScreenKeyboardInputType.Numeric`
`KeyboardSize`	Gets or sets the default keyboard visual width. Possible values:`FullWidth`, `Small`, `Medium`, `Large`	`OnScreenKeyboardSize`	`OnScreenKeyboardSize.Medium`
`KeyLayout`	Gets or sets the default key arrangement inside keyboard rows. Possible values:`Stretch`, `Centered`	`OnScreenKeyboardKeyLayout`	`OnScreenKeyboardKeyLayout.Centered`
`KeyMinHeight`	Gets or sets the key minimum height, in pixels.	`int?`	`null`
`KeyWidth`	Gets or sets the base key width, in pixels, used by centered key layout.	`int?`	`null`
`Placement`	Gets or sets the default keyboard placement. Possible values:`Bottom`, `Top`, `Inline`	`OnScreenKeyboardPlacement`	`OnScreenKeyboardPlacement.Bottom`
`ShowMode`	Gets or sets how the on-screen keyboard is shown for enabled input components. Possible values:`Default`, `Focus`, `Manual`	`OnScreenKeyboardShowMode`	`OnScreenKeyboardShowMode.Focus`
`ShowSpecialCharactersKey`	If true, the text keyboard includes a key that toggles special characters.	`bool`	`false`
`SpecialCharactersRows`	Gets or sets the rows used when the special characters keyboard is active.	`IReadOnlyList<IReadOnlyList<OnScreenKeyboardKey>>`	`null`

Events

OnScreenKeyboardProvider

Event	Description	Type
`LayoutProvider`	Gets or sets a function that resolves keyboard rows for the active input context.	`Func<OnScreenKeyboardContext, IReadOnlyList<IReadOnlyList<OnScreenKeyboardKey>>>`

BaseOnScreenKeyboardInputComponent

Event	Description	Type
`Blur`	The blur event fires when an element has lost focus.	`EventCallback<FocusEventArgs>`
`CustomValidationValue`	Used to provide custom validation value on which the validation will be processed with the Validator handler. Remarks Should be used carefully as it's only meant for some special cases when input is used in a wrapper component, like Autocomplete or SelectList.	`Func<TValue>`
`FocusIn`	Notifies when the input box gains focus.	`EventCallback<FocusEventArgs>`
`FocusOut`	Notifies when the input box loses focus.	`EventCallback<FocusEventArgs>`
`KeyDown`	Notifies when a key is pressed down while the control has focus.	`EventCallback<KeyboardEventArgs>`
`KeyPress`	Notifies when a key is pressed while the control has focus.	`EventCallback<KeyboardEventArgs>`
`KeyUp`	Notifies when a key is released while the control has focus.	`EventCallback<KeyboardEventArgs>`
`OnFocus`	Notifies when the input box gains or loses focus.	`EventCallback<FocusEventArgs>`
`ValueChanged`	Occurs after value has changed.	`EventCallback<TValue>`

BlazoriseOnScreenKeyboardOptions

Event	Description	Type
`LayoutProvider`	Gets or sets a function that resolves keyboard rows for a focused input.	`Func<OnScreenKeyboardContext, IReadOnlyList<IReadOnlyList<OnScreenKeyboardKey>>>`
`LayoutSelector`	Gets or sets a function that resolves the keyboard layout for a focused input.	`Func<OnScreenKeyboardContext, OnScreenKeyboardLayout>`
`ShouldShow`	Gets or sets a predicate that decides if the keyboard should be shown for a focused input.	`Func<OnScreenKeyboardContext, bool>`

Methods

BaseOnScreenKeyboardInputComponent

Method	Description	Return	Parameters
`ShowOnScreenKeyboard`	Shows the on-screen keyboard for this input.	`Task`	`bool focus`
`Focus`	Sets the focus on the underline element.	`Task`	`bool scrollToElement`
`Revalidate`	Forces the Validation (if any is used) to re-validate with the new custom or internal value.	`Task`

Blazorise On-screen Keyboard

Provider setup

Examples

Text input

Button trigger

Memo input

Input-specific layouts

Special characters

Custom layouts

Keyboard size and layout

Key template

Global option

API

Parameters

OnScreenKeyboardProvider

BaseOnScreenKeyboardInputComponent

BlazoriseOnScreenKeyboardOptions

Events

OnScreenKeyboardProvider

BaseOnScreenKeyboardInputComponent

BlazoriseOnScreenKeyboardOptions

Methods

BaseOnScreenKeyboardInputComponent

On this page