UI Labs

Appearance

Fusion ​

Providing your library ​

To provide your library you will need to add the following keys to your story table:

KeyTypeDescription
fusion   RequiredFusionFusion library to be used

Rendering your story ​

Fusion stories will be renderer by calling the story function once.

When they are executed, Fusion components need to be created in the target frame that can be found in the props table.

lua
local story = {
   fusion = Fusion,
   controls = controls,
   story = function(props)
      local component = Fusion.New "Frame" {
         Parent = props.target,
      }
   end
}
local story = {
   fusion = Fusion,
   controls = controls,
   story = function(props)
      local component = Fusion.New "Frame" {
         Parent = props.target,
      }
   end
}
tsx
const story = {
   fusion: Fusion,
   controls: controls,
   story: (props: InferFusionProps<typeof controls>) => {
      const component = Fusion.New("Frame")({
         Parent: props.target,
      })
   }
}
const story = {
   fusion: Fusion,
   controls: controls,
   story: (props: InferFusionProps<typeof controls>) => {
      const component = Fusion.New("Frame")({
         Parent: props.target,
      })
   }
}

Using controls ​

UI Labs will create Fusion.Value's for every control and it will update them when the control changes. These controls will be available in the props table.

lua
local controls = {
   Visible = true
}

local story = {
   fusion = Fusion,
   controls = controls,
   story = function(props)
      local component = Fusion.New "Frame" {
         Parent = props.target,
         Size = UDim2.fromOffset(200, 100),
         Visible = props.controls.Visible -- This will be a Fusion.Value<boolean>
      }
   end
}
local controls = {
   Visible = true
}

local story = {
   fusion = Fusion,
   controls = controls,
   story = function(props)
      local component = Fusion.New "Frame" {
         Parent = props.target,
         Size = UDim2.fromOffset(200, 100),
         Visible = props.controls.Visible -- This will be a Fusion.Value<boolean>
      }
   end
}
tsx
const controls = {
   Visible: true
}

const story = {
   fusion: Fusion,
   controls: controls,
   story: (props: InferFusionProps<typeof controls>) => {
      const component = Fusion.New("Frame")({
         Parent: props.target,
         Size: UDim2.fromOffset(200, 100),
         Visible: props.controls.Visible // This will be a Fusion.Value<boolean>
      })
   }
}
const controls = {
   Visible: true
}

const story = {
   fusion: Fusion,
   controls: controls,
   story: (props: InferFusionProps<typeof controls>) => {
      const component = Fusion.New("Frame")({
         Parent: props.target,
         Size: UDim2.fromOffset(200, 100),
         Visible: props.controls.Visible // This will be a Fusion.Value<boolean>
      })
   }
}

Cleaning up ​

After the function is executed, it can return two things:

  • A Roblox instance that will be destroyed when the story is unmounted
  • A cleanup function that will be called when the story is unmounted
Example
lua
local story = {
   fusion = Fusion,
   controls = controls,
   story = function(props)
      local component = Fusion.New "Frame" {
         Parent = props.target,
      }
      
      return function()
         component:Destroy()
      end
   end
}
local story = {
   fusion = Fusion,
   controls = controls,
   story = function(props)
      local component = Fusion.New "Frame" {
         Parent = props.target,
      }
      
      return function()
         component:Destroy()
      end
   end
}
tsx
const story = {
   fusion: Fusion,
   controls: controls,
   story: (props: InferFusionProps<typeof controls>) => {
      const component = Fusion.New("Frame")({
         Parent: props.target,
      })
      
      return () => {
         component.Destroy()
      }
   }
}
const story = {
   fusion: Fusion,
   controls: controls,
   story: (props: InferFusionProps<typeof controls>) => {
      const component = Fusion.New("Frame")({
         Parent: props.target,
      })
      
      return () => {
         component.Destroy()
      }
   }
}

Using Fusion 0.3 ​

Fusion 0.3 introduced scopes as a way to cleanup multiple objects. You can acccess the scope where the controls are created by using the scope key in the props table.

This scope will be destroyed with Fusion.doCleanup when the story is unmounted. This implies that the cleanup function is not needed in most cases, because of this, the cleanup function/instance can be optional.

Cleanup

Not returning a cleanup in Fusion 0.2 will result in a warning.

Example
lua
local Fusion = require(...)

local controls = { ... }

local story = { 
   fusion = Fusion,
   controls = controls,
   story = function(props)
      local scope = props.scope

      local value = scope:Value("foo")
      local component = scope:New "Frame" {
         Parent = props.target,
      }
      -- cleanup function is not needed
   end,
}
local Fusion = require(...)

local controls = { ... }

local story = { 
   fusion = Fusion,
   controls = controls,
   story = function(props)
      local scope = props.scope

      local value = scope:Value("foo")
      local component = scope:New "Frame" {
         Parent = props.target,
      }
      -- cleanup function is not needed
   end,
}
tsx
// Waiting for Fusion 0.3 in roblox-ts
// Waiting for Fusion 0.3 in roblox-ts

Using the Story Creator ​

You can use the Story Creator in the Utility Package to create your story. These will infer the control types for Roblox-TS.

UILabs.CreateFusionStory(info, story):StoryTable

Example
lua
local Fusion = require(...)

local UILabs = require(...)
local CreateFusionStory = UILabs.CreateFusionStory

local controls = { ... }

local story = CreateFusionStory({ 
   fusion = Fusion,
   controls = controls,
}, function(props)
   local component = Fusion.New "Frame" {
      Parent = props.target,
   }
   
   return function()
      component:Destroy()
   end
end)
local Fusion = require(...)

local UILabs = require(...)
local CreateFusionStory = UILabs.CreateFusionStory

local controls = { ... }

local story = CreateFusionStory({ 
   fusion = Fusion,
   controls = controls,
}, function(props)
   local component = Fusion.New "Frame" {
      Parent = props.target,
   }
   
   return function()
      component:Destroy()
   end
end)
tsx
import Fusion from "@rbxts/fusion"
import { CreateFusionStory } from "@rbxts/ui-labs"

const controls = { ... }

const story = CreateFusionStory({
   fusion: Fusion,
   controls: controls,
}, (props: InferFusionProps<typeof controls>) => {
   const component = Fusion.New("Frame")({
      Parent: props.target,
   })
   
   return () => {
      component.Destroy()
   }
})
import Fusion from "@rbxts/fusion"
import { CreateFusionStory } from "@rbxts/ui-labs"

const controls = { ... }

const story = CreateFusionStory({
   fusion: Fusion,
   controls: controls,
}, (props: InferFusionProps<typeof controls>) => {
   const component = Fusion.New("Frame")({
      Parent: props.target,
   })
   
   return () => {
      component.Destroy()
   }
})