File Associations

Relevant Platforms: Windows macOS

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

Listening for File Open Events

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

package main

import (
    "github.com/wailsapp/wails/v3/pkg/application"
    "github.com/wailsapp/wails/v3/pkg/events"
)

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.Event.OnApplicationEvent(events.Common.ApplicationOpenedWithFile, func(event *application.ApplicationEvent) {
        associatedFile := event.Context().Filename()
        app.Dialog.Info().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:

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

wails3 update build-assets

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

wails3 package