wails/mkdocs-website/docs/en/learn/guides/file-associations.md

File Associations

File associations allow your application to handle specific file types when users open them. This is particularly useful for text editors, image viewers, or any application that works with specific file formats. This guide explains how to implement file associations in your Wails v3 application.

Overview

File association support in Wails v3 is currently available for:

• Windows (NSIS installer packages)
• macOS (application bundles)

Configuration

File associations are configured in the config.yml file located in your project's build directory.

Basic Configuration

To set up file associations:

1. Open build/config.yml
2. Add your file associations under the fileAssociations section
3. Run wails3 update build-assets to update the build assets
4. Set the FileAssociations field in the application options
5. Package your application using wails3 package

Here's an example configuration:

fileAssociations:
  - ext: myapp
    name: MyApp Document
    description: MyApp Document File
    iconName: myappFileIcon
    role: Editor
  - ext: custom
    name: Custom Format
    description: Custom File Format
    iconName: customFileIcon
    role: Editor

Configuration Properties

Property	Description	Platform
ext	File extension without the leading period (e.g., txt)	All
name	Display name for the file type	All
description	Description shown in file properties	Windows
iconName	Name of the icon file (without extension) in the build folder	All
role	Application's role for this file type (e.g., Editor, Viewer)	macOS

Listening for File Open Events

To handle file open events in your application, you can listen for the events.Common.ApplicationOpenedWithFile event:

func main() {
    app := application.New(application.Options{
		Name: "MyApp", 
		FileAssociations: []string{".txt", ".md"}, // Specify supported extensions
    }) 
	
	// Listen for files being used to open the application
	app.OnApplicationEvent(events.Common.ApplicationOpenedWithFile, func(event *application.ApplicationEvent) {
        associatedFile := event.Context().Filename()
		application.InfoDialog().SetMessage("Application opened with file: " + associatedFile).Show()
	}) 
	
	// Create your window and run the app...
}

Step-by-Step Tutorial

Let's walk through setting up file associations for a simple text editor:

1. Create Icons

• Create icons for your file type (recommended sizes: 16x16, 32x32, 48x48, 256x256)
• Save the icons in your project's build folder
• Name them according to your iconName configuration (e.g., textFileIcon.png)

!!! tip You can use wails3 generate icons to generate the required icons for you. Run wails3 generate icons --help for more information.

2. Configure File Associations

Edit the build/config.yml file to add your file associations:

# build/config.yml
fileAssociations:
  - ext: txt
    name: Text Document
    description: Plain Text Document
    iconName: textFileIcon
    role: Editor

3. Update Build Assets

Run the following command to update the build assets:

wails3 update build-assets

4. Set File Associations in the Application Options

In your main.go file, set the FileAssociations field in the application options:

    app := application.New(application.Options{  
	    Name: "MyApp",
	    FileAssociations: []string{".txt", ".md"}, // Specify supported extensions
	})

??? question "Why do the file extensions need to be set in the application config when it's set in config.yml?"

  On Windows, when a file is opened with a file association, the application is launched with the filename as the first argument to the application.
  The application has no way of knowing if the first argument is a file or a command line argument, so it uses the `FileAssociations` field in the application options to determine if the first argument is an associated file or not.

5. Package Your Application

Package your application using the following command:

wails3 package

The packaged application will be created in the bin directory. You can then install and test the application.

Additional Notes

• Icons should be provided in PNG format in the build folder
• Testing file associations requires installing the packaged application