Element Creation

create()

Creates a new UI element, applying any given properties.

• Type

  function create(class: string): (Properties) -> Instance
  function create(instance: Instance): (Properties) -> Instance
  
  type Properties = Map<string|number, unknown>

• Details

  The function can take either a string or an Instance as its first argument.

  • If given a string, a new instance with the same class name will be created.
  • If given an Instance, a new instance that is a clone of the given instance will be created.

  This returns another function that is used to apply any properties to the new instance.

• Property setting rules

  • index is string:
    • value is function:
      • property is event: connect function as callback
      • property is not event: create effect to update property
    • value is not function: set property to value
  • index is number:
    • value is action: run action
    • value is table: recurse table
    • value is function: create effect to update children
    • value is instance: set instance as child

• Example

  Basic element creation.

  local frame = create "TextButton" {
      Name = "Button",
      Size = UDim2.fromOffset(200, 160),
  
      Activated = function()
          print "clicked"
      end,
  
      create "UICorner" {}
  }

action()

Creates a special object that can be passed to create() to invoke custom actions on instances.

• Type

  function action((Instance) -> (), priority: number = 1): Action

• Details

  When passed to create(), the function is called with the instance being created as the only argument. Actions take precedence over property and child assignments.

  A priority can be optionally specified to ensure certain actions run after other actions. Lower priority values are ran first.

• Example

  An action to listen to changed properties:

  local function changed(property: string, fn: (new) -> ())
      return action(function(instance)
          local cn = instance:GetPropertyChangedSignal(property):Connect(function()
              fn(instance[property])
          end)
  
          -- disconnect on scope destruction to allow gc of instance
          cleanup(function()
              cn:Disconnect()
          end)
      end)
  end
  
  local output = source ""
  
  create "TextBox" {
      -- will update the output source anytime the text property is changed
      changed("Text", output)
  }

changed()

A wrapper for action() to listen for property changes.

• Type

  function changed(property: string, fn: (unknown) -> ()): Action

• Details

  Will run the given function immediately and whenever the property updates.

  The function is called with the updated property value.

  Runs with an action priority of 1.

mount() STABLE

Runs a function in a new stable scope and optionally applies its result to a target instance.

• Type

  function mount<T>(component: () -> T, target: Instance?): () -> ()

• Details

  This is a utility for root() when parenting a component to an existing instance.

  The result of the function is applied to a target in the same way properties are using create().

  Returns a function that when called will destroy the stable scope.

• Example

  local function App()
      return create "ScreenGui" {
          create "TextLabel" { Text = "Vide" }
      }
  end
  
  local destroy = mount(App, game.StarterGui)