vide/docs/api/creation.md

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.

tag()

A wrapper for action() to add CollectionService tags to an instance.

• Type

  function tag(tag: string): Action
  function tag(tags: { string }): Action
  function tag(source: () -> string): Action
  function tag(source: () -> { string }): Action
  

• Details

  Adds the given tag(s) to the instance using Instance:AddTag(). When the surrounding scope is destroyed, any tags that were added are removed using Instance:RemoveTag().

  A source (function) can be passed instead of a static value to reactively update the applied tags. When the source updates, tags no longer present are removed and new tags are added; tags present in both the previous and new value are left untouched.

  Multiple tag() actions can be composed on the same instance.

  Runs with an action priority of 1.

• Example

  Apply static tags:

  create "Frame" {
      tag("Clickable"),
      tag({ "Draggable", "Highlightable" })
  }
  

  Apply a reactive tag driven by a source:

  local state = source "idle"
  
  create "Frame" {
      tag(function() return "state-" .. state() end)
  }
  

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)