Using Table-specific Icons

Changing the graphical element displayed by an Icon component is as easy as entering a different name in the name property:

<Icon name="email" />

Some components have icons already built into them like the ones in the Table component indicating sorting by a specific column.

📔

The following examples all use the same dataset that the Table component reference documentation uses.

The Table uses three icons to indicate the sorting order for the three possible icon options:

ascending: sortasc
descending: sortdesc
not sorted by the column: nosort

If you want to use your own icons instead of the ones already provided, you would add an entry with the icon name to the configuration file like so:

{
  name: "My Project",
  resources: {
    "icon.arrowup": "resources/arrow-up.svg",
  },
}

However, this would change all icons using the name arrowup.

Component-specific Custom Icons

💡

In situations where you would want to change only the icon(s) of a particular component, like the Table, you can use icon names scoped specifically to that component.

Component-scoped icon names follow the same signature:

<icon-name>:<component-name>

Icons in the Table component using this signature are the following icons:

sortasc:Table
sortdesc:Table
nosort:Table

Use the same method for overwriting these icons as you would do with other icons:

{
  name: "My Project",
  resources: {
    "icon.sortasc:Table": "resources/arrow-up.svg",
  },
}

This ensures that only the sortasc icon found in the Table component is affected by the change.

Instance-specific Custom Icons

Another scenario regarding icon change is where only one instance of the Table component on a particular page needs to have different sorting icons. The Table component also supports this case by providing the following properties:

iconSortAsc: overwrites the "sortasc:Table" icon
iconSortDesc: overwrites the "sortdesc:Table" icon
iconNoSort: "overwrites the "nosort:Table" icon

In the next example, the first Table component to the left retains the default sort by ascending order icon, while the second Table to the right uses the chevronup icon instead.

<App>
  <HStack>
    <VStack width="50%">
      Default icon:
      <Table data='{...}' sortBy="name">
        <Column bindTo="name" canSort="true"/>
        <Column bindTo="quantity" canSort="true"/>
      </Table>
    </VStack>
    <VStack width="50%">
      Instance-specific icon:
      <Table data='{...}' iconSortAsc="chevronup" sortBy="name">
        <Column bindTo="name" canSort="true"/>
        <Column bindTo="quantity" canSort="true"/>
      </Table>
    </VStack>
  </HStack>
</App>

Fallbacks

Scoped icons always fall back to a more generic alternative if a particular name is not found. XMLUI uses the same concept here as it does regarding theme variable chaining. From the most specific to the most generic the chain looks like the following for the Table's sortasc icon:

XMLUI looks for the sortasc:Table icon name in the resources of the application config
If (1) is not found, XMLUI checks the same resources entry in the config file for an icon name sortasc
If (2) is not found, XMLUI browses the icon registry for an icon name sortasc
If none of the above is found, XMLUI renders an empty icon

This also means that if more than one icon is set, the icon that is more specific will overwrite a more generic icon. In the following example, we will override the icon.sortasc:Table resource with a custom one and also set the iconSortAsc property. Note, how the icon resource only appears in the left Table and not on the right one which has the property set:

config.ts

{
  name: "My Project",
  resources: {
    "icon.sortasc:Table": "resources/arrow-up.svg",
  },
}

Main.xmlui

<HStack>
  <VStack width="50%">
    Component-specific icon:
    <Table data='{[...]}' sortBy="name">
      <Column bindTo="name" canSort="true"/>
      <Column bindTo="quantity" canSort="true"/>
    </Table>
  </VStack>
  <VStack width="50%">
    Instance-specific icon:
    <Table data='{[...]}' iconSortAsc="chevronup" sortBy="name">
      <Column bindTo="name" canSort="true"/>
      <Column bindTo="quantity" canSort="true"/>
    </Table>
  </VStack>
</HStack>

Events Customizing Input Fields