Basic Components

XMLUI ships with several simple, easy-to-use components for various tasks. In this article, you will learn some basic usage patterns of them.

Button

Use the Button component to let users trigger various actions on the UI.

<App>
  <Button label="Click me!" onClick="toast('Button clicked')" />
  <Button label="Can't Click Here" enabled="{false}" />
</App>

💡

Certain buttons can be emphasized by using properties such as variant, themeColor and size.

<App>
  <HStack>
    <Button label="Solid" themeColor="primary" />
    <Button label="Solid" themeColor="secondary" />
    <Button label="Solid" themeColor="attention" />
  </HStack>
  <HStack>
    <Button label="Outlined" variant="outlined" themeColor="primary" />
    <Button label="Outlined" variant="outlined" themeColor="secondary" />
    <Button label="Outlined" variant="outlined" themeColor="attention" />
  </HStack>
  <HStack>
    <Button label="Ghost" variant="ghost" themeColor="primary" />
    <Button label="Ghost" variant="ghost" themeColor="secondary" />
    <Button label="Ghost" variant="ghost" themeColor="attention" />
  </HStack>
 
  <HStack verticalAlignment="center">
    <Button label="Size xs" size="xs" />
    <Button label="Size sm" size="sm" />
    <Button label="Size md" size="md" />
    <Button label="Size lg" size="lg" />
  </HStack>
</App>

💡

Buttons can also have icons to provide visual cues.

<App>
  <HStack>
    <Button icon="close" variant="ghost" themeColor="secondary" />
    <Button label="Clear Text Field" icon="trash" iconPosition="end"
      variant="outlined" themeColor="secondary" />
    <Button label="Update" icon="pen" />
  </HStack>
</App>

See the Button component reference to know more.

Checkbox

The Checkbox component allows users to make binary choices by toggling an input control on or off.

It works the same way as the Switch component - the only difference is that the Checkbox also has an indeterminate state.

<App>
  <HStack>
    Enabled checkboxes:
    <Checkbox id="check1" initialValue="true" enabled="true" />
    <Checkbox id="check2" initialValue="false" enabled="true" />
  </HStack>
  <HStack>
    Checkbox values:
    <Text value="{check1.value}" />
    <Text value="{check2.value}" />
  </HStack>
  <HStack>
    Disabled checkboxes:
    <Checkbox initialValue="true" enabled="false" />
    <Checkbox initilaValue="false" enabled="false" />
  </HStack>
</App>

The Checkbox component can indicate the state of a group of other checkboxes. This state is visual only, the actual value of the checkbox is still either true or false.

💡

Get the data of an input control by assigning an ID to it and using dot notation to access its value.

<App>
  <Checkbox
    indeterminate="true"
    label="Indeterminate Indicator"
    initialValue="true"
    readOnly="true" />
</App>

Find out more in the Checkbox reference.

Switch

The Switch component allows users to make binary choices by toggling an input control on or off.

It works the same way as the Checkbox component - the only difference is that the Checkbox also has an indeterminate state.

<App>
  <HStack>
    Enabled switches:
    <Switch id="switch1" initialValue="true" enabled="true" />
    <Switch id="switch2" initialValue="false" enabled="true" />
  </HStack>
  <HStack>
    Switch values:
    <Text value="{switch1.value}" />
    <Text value="{switch2.value}" />
  </HStack>
  <HStack>
    Disabled switches:
    <Switch initialValue="true" enabled="false" />
    <Switch initilaValue="false" enabled="false" />
  </HStack>
</App>

Find out more in the Switch reference.

RadioGroup

This component can contain a set of radio group buttons (RadioGroupOption) and enable the selection of only one of them at any one time.

<App>
  <RadioGroup id="group1" initialValue="first">
    <HStack>
      <Option label="First Item" value="first"/>
      <Option label="Second Item" value="second"/>
      <Option label="Third Item" value="third"/>
    </HStack>
  </RadioGroup>
  <Text value="RadioGroup value: {group1.value}" />
</App>

Both the grouping component (RadioGroup) and its options (RadioGroupOption) can be enabled and disabled.

<App>
  <HStack>
    <RadioGroup initialValue="first">
      <VStack>
        <Option label="First Item" value="first" enabled="false" />
        <Option label="Second Item" value="second" enabled="false" />
        <Option label="Third Item" value="third" />
      </VStack>
    </RadioGroup>
    <RadioGroup initialValue="first" enabled="false">
      <VStack>
        <Option label="First Item" value="first"/>
        <Option label="Second Item" value="second"/>
        <Option label="Third Item" value="third"/>
      </VStack>
    </RadioGroup>
  </HStack>
</App>

Details can be found in the RadioGroup component reference.

DatePicker

Enables the selection of a date or a range of dates in a specified format from an interactive display.

<App>
  <DatePicker dateFormat="dd/MM/yyyy" initialValue="25/05/2024" />
  <DatePicker dateFormat="yyyy-MM-dd" initialValue="25/05/2024" />
  <DatePicker dateFormat="MMddyyyy" initialValue="25/05/2024" />
</App>

💡

Use the mode property to specify the number of selectable dates: "single" or "range".

<App>
  <DatePicker initialValue="25/05/2024" mode="single" />
  <DatePicker initialValue="{{ from: '25/05/2024', to: '25/07/2024' }}" mode="range" />
</App>

For further details see the DatePicker component reference.

NumberBox

A NumberBox component allows users to input numeric values: integer or floating point numbers.

<App>
  <NumberBox initialValue="123" />
  <NumberBox initialValue="123" hasSpinBox="false" />
  <NumberBox initialValue="123" enabled="false" />
  <NumberBox initialValue="123" enabled="false" hasSpinBox="false" />
</App>

💡

You can provide different kinds of constraints on what numbers the input field accepts.

<App>
  <VStack>
    Integers Only
    <NumberBox integersOnly="true" initialValue="123" />
  </VStack>
  <VStack>
    Zero or Positive Numbers Only
    <NumberBox zeroOrPositive="true" initialValue="1" />
  </VStack>
  <VStack>
    Minimum and Maximum Values
    <NumberBox minValue="-10" maxValue="10" initialValue="1" />
  </VStack>
  <VStack>
    Maximum Length
    <NumberBox maxLength="3" initialValue="123" />
  </VStack>
</App>

See the NumberBox component reference to know more.

Select

Provides a dropdown with a list of options to choose from. For selecting multiple items from a list, refer to the MultiSelect component.

<App>
  <Select>
    <Option value="opt1" label="first" />
    <Option value="opt2" label="second" />
    <Option value="opt3" label="third" />
  </Select>
  <Select>
    <Items items="{['first', 'second', 'third']}">
      <Option label="{$item} option" value="{$item}" />
    </Items>
  </Select>
</App>

The list items and the empty list display are both customizable.

See the Select component reference to know more.

TextArea

The TextArea component provides is a multiline text input component. To add new lines to the input field, press Shift + Enter.

<App>
  <TextArea initialValue="I am a TextArea component." placeholder="Enter text..." />
  <TextArea initialValue="I am a disabled TextArea component." enabled="false" />
</App>

💡

Control the number of rows, as well as minimum and maximum row numbers via properties.

Note that if either autoSize, maxRows or minRows is set, the rows property has no effect.

<App>
  <!-- Display exactly three rows no matter the content -->
  <TextArea rows="3" initialValue="Lorem ipsum dolor sit amet..." />
  <!-- Display at most three rows but show less if there is not enough content -->
  <TextArea
    maxRows="3"
    initialValue="Lorem ipsum dolor sit amet,
    consectetur adipiscing elit,
    sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
    Ut enim ad minim veniam,
    quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat." />
  <!-- Display at least three rows and grow if necessary -->
  <TextArea
    minRows="3"
    initialValue="Lorem ipsum dolor sit amet,
    consectetur adipiscing elit,
    sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
    Ut enim ad minim veniam,
    quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat." />
</App>

💡

Limit how the user can resize the TextArea.

<App>
  <TextArea
    resize="vertical"
    initialValue="You can resize me vertically" />
  <TextArea
    resize="horizontal"
    initialValue="You can resize me horizontally" />
  <TextArea
    resize="both"
    initialValue="You can resize me both ways" />
</App>

See the TextArea component reference to know more.

TextBox

The TextBox is an input component that allows users to input and edit textual data.

<App>
  <TextBox initialValue="I am a TextBox" placeholder="Write something here..." />
  <TextBox initialValue="I am a TextBox" enabled="false" />
</App>

For details, see the TextBox component reference.

Link

A Link component represents a hyperlink used to link from one page to another (can be a subpage of the app or external).

💡

Note: The target property set to "_blank" ensures the link opens in a new tab.

<App>
  <Link to="https://docs.xmlui.com/" target="_blank">
    XMLUI introduction
  </Link>
  <Link to="https://docs.xmlui.com/" enabled="false" target="_blank">
    Disabled XMLUI introduction
  </Link>
</App>

💡

Add an icon and text via relevant properties to leverage built-in styling.

<App>
  <Link
    label="XMLUI introduction"
    icon="star"
    target="_blank"
    to="https://docs.xmlui.com/" />
</App>

💡

The Link component is hooked up the the XMLUI routing system. See this article for details.

Also see the Link component reference to know more about the component itself.

Badge

The Badge is a text label that accepts a color map to define its background color and, optionally, its label color.

<App>
  <variable name="simpleColorMap" value="{{ important: 'red', regular: 'blue', unimportant: 'black' }}" />
  Regular Badge
  <HStack>
    <Badge value="no mapped color" colorMap="{simpleColorMap}" />
    <Badge value="important" colorMap="{simpleColorMap}" />
    <Badge value="regular" colorMap="{simpleColorMap}" />
    <Badge value="unimportant" colorMap="{simpleColorMap}" />
  </HStack>
  Pill Shaped Badge
  <HStack>
    <Badge variant="pill" value="no mapped color" colorMap="{simpleColorMap}" />
    <Badge variant="pill" value="important" colorMap="{simpleColorMap}" />
    <Badge variant="pill" value="regular" colorMap="{simpleColorMap}" />
    <Badge variant="pill" value="unimportant" colorMap="{simpleColorMap}" />
  </HStack>
</App>

Also see the Badge component reference to know more about the component itself.

Card

The Card component is a container for grouping other UI elements. It visually separates its content from its surroundings.

<App>
  <Card>
    <HStack>
      <Icon name="info" />
      <Text value="Information" variant="strong" />
    </HStack>
    This is an example text
  </Card>
</App>

💡

The component also provides prestyled elements that are accessible via the Card properties.

<App>
  <Card
    avatarUrl="https://i.pravatar.cc/100"
    title="Predefined Title"
    subtitle="Predefined Subtitle">
    <HStack>
      <Icon name="info"/>
      This is the content of the card. You can place anything here.
      Currently, it contains an icons with some example text.
    </HStack>
  </Card>
</App>

Icon

This component is the representation of an icon.

<App>
  <HStack>
    <Icon name="message" />
    <Icon name="note" />
    <Icon name="cog" />
    <Icon name="start" />
  </Hstack>
</App>

💡

If an icon name does not correspond to a valid graphical element, you can use a fallback icon. No icon is rendered if no fallback is specified.

<App>
  <HStack>
    No icon displayed:
    <Icon name="non-existing-icon" />
  </HStack>
  <HStack>
    Fallback displayed:
    <Icon name="non-existing-icon-with-fallback" fallback="trash" />
  </HStack>
</App>

💡

It is possible to use your own icons instead of the built-in ones and also define new icons using the resource attribute in the app config file.

See the Icon component reference to know more.

Image

The Image component can display complex graphical images. It functions as a container for a picture.

<App>
  <Image src="/resources/images/components/image/breakfast.jpg" width="240px" />
  <Image 
    src="cantFindIt.jpg" 
    alt="This image depicts a wonderful scene not for human eyes" 
    width="240px" />
</App>

See the Image component reference to know more.

ProgressBar

A ProgressBar component visually represents the progress of a task or process.

<App>
  <ProgressBar value="0"/>
  <ProgressBar value="0.2"/>
  <ProgressBar value="0.6"/>
  <ProgressBar value="1"/>
  <ProgressBar value="1.2"/>
</App>

💡

Use some kind of logic when setting the value property to represent change.

See the ProgressBar component reference to know more.

Spinner

The Spinner component is an animated indicator that represents a particular action in progress without a deterministic progress value.

<App>
  <Spinner />
</App>

💡

Use the delay property to control when the Spinner is displayed.

Use the buttons to toggle between the two Spinners in the demo app:

<App>
  <variable name="noDelay" value="{true}" />
  <variable name="yesDelay" value="{false}" />
  <HStack>
    <Button
      label="No delay"
      onClick="noDelay = true; yesDelay = false;" />
    <Button
      label="1000 ms delay"
      onClick="noDelay = false; yesDelay = true;" />
  </HStack>
  <Spinner when="{noDelay}" delay="0" />
  <Spinner when="{yesDelay}" delay="1000" />
</App>

For further details see the Spinner component reference.

ContentSeparator

A ContentSeparator is a component that divides or separates content visually within a layout.

<App>
  <Heading level="h2">
    Lorem Ipsum
  </Heading>
  <ContentSeparator />
  Lorem ipsum dolor sit amet, consectetur adipiscing elit,
  sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
  Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi
  ut aliquip ex ea commodo consequat.
  <ContentSeparator orientation="horizontal" />
  <HStack>
    Duis aute irure dolor in reprehenderit in voluptate velit esse cillum
    dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat
    non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
    <ContentSeparator orientation="vertical" />
    Sed ut perspiciatis unde omnis iste natus error sit voluptatem
    accusantium doloremque laudantium, totam rem aperiam,
    eaque ipsa quae ab illo inventore veritatis et quasi architecto
    beatae vitae dicta sunt explicabo.
  </HStack>
</App>

See the ContentSeparator component reference to know more.

Working with Text Working with Data