Beyond the Basics: Easy Icon Placement on .NET MAUI Buttons

This small detail can really polish your app: Getting the icons placed just right inside your buttons. Learn how to do this in .NET MAUI.

Many of us know how to add an icon to a button in our apps, but controlling its position and spacing relative to the text is less common. This minor detail can significantly influence adherence to the design guidelines provided by your designer. In this article, I’ll demonstrate a simple property to control these aspects. 🚀

The ImageSource Property

If you’re unfamiliar with it, the Button class has the ImageSource property which lets you display a Bitmap image on a Button. The image can be loaded from various sources like a file, embedded resource, URI or stream.

It’s important to understand that bitmaps don’t automatically scale to fit a button. According to official guidelines, the ideal size for such images usually ranges between 32 and 64 device-independent units. The size selection should rely on your preferred bitmap dimensions. Following these guidelines can ensure that your images seamlessly fit your buttons.

<Button Text="Click for help"
  ImageSource="help_circled.png"/>

⚠️ Keep in mind: When naming an image, please ensure compliance with Android resource naming rules, which are as follows:

• Image file names must be in lowercase.
• They should start and end with a letter character and contain only alphanumeric characters or underscores.

For more information about these rules, I invite you to read the app resources overview document.

Positioning the Image on the Button 🤓

For this, you need to know about ContentLayout.

The ContentLayout property manages the arrangement of both the image and/or text within a button. This property is relevant only when the elements it affects are present. For example, to adjust text spacing, the Text property must be assigned to the button. The same rule applies to ImageSource. ContentLayout is of the type ButtonContentLayout and its constructor has two arguments, which are as follows:

• Image Position: Specifies where the bitmap will be displayed in relation to the button’s text. The default position is on the left. It accepts one of the values from the ImagePosition enumeration, which includes the following values:

• Spacing: This represents the gap between the bitmap and the text. It accepts a double value.

Each value can be added independently or together. If you wish to alter the icon’s position without affecting text spacing, you can do so, and the same applies in reverse. Note that if you only modify the spacing, it will be relative to the default position of the icon, which is on the left.

You may also use both values, but they must be separated by a comma. For instance, ContentLayout="Bottom, 20". See the full example below:

<Button Text="Click for help"
  ImageSource="help_circled.png"
  ContentLayout="Right, 10"/>

Using C# Code

You can adjust the position either by setting it directly in the XAML code, as demonstrated above, or by using C# code. Choose the approach that best aligns with your preferences and development workflow.

Button button = new Button 
{ 
  Text = "Click for help", 
  ImageSource = new FileImageSource 
  { 
    File = "help_circled.png" 
  }, 
  ContentLayout = new Button.ButtonContentLayout(Button.ButtonContentLayout.ImagePosition.Right, 10) 
};

And there you have it! 🎉 With this simple property, you can control the positioning and spacing of your button icons. Below, I will provide visual examples of each available positioning option. Let’s explore!

Conclusion

That’s it! 🎉 You’ve now learned how to effectively manage icon positions on your .NET MAUI buttons. I hope you found this article helpful! Feel free to start implementing this property in your daily projects! 💚💕

See you next time! 💁‍♀️

References

This article was based on the official documentation:

• https://learn.microsoft.com/en-us/dotnet/maui/user-interface/controls/button?view=net-maui-8.0