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.

Configuration

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. 
<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. 
<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. 
<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. 
<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 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;
    } );

Best Practices

Input Alternatives

An on-screen keyboard should complement physical keyboards and assistive technology rather than replace them. Enable it only for the input types and devices that benefit from it so the keyboard does not obscure content unnecessarily.

Input Locale

Layouts, decimal separators, special characters, and action keys should reflect both the input's purpose and the user's locale. Keep password and sensitive-data behavior consistent with the underlying input, and never record keystrokes for diagnostics.

API

See the API reference for the parameters, events, methods, and related types available to the components covered on this page.

On this page