vide/docs/api/creation.md

Element Creation API

mount()

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

• Type

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

• Details

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

  The function is ran in a new reactive scope, just like root().

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

• Example

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

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, any>
  

• 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 "Frame" {
      Name = "NewFrame",
      Position = UDim2.fromScale(1, 0)
  }
  

  A component using property nesting.

  type Layout = {
      Layout = {
          Position: UDim2?,
          Size: UDim2?,
          AnchorPoint: Vector2?
      }
  }
  
  type Children = {
      Children = Array<Instance>
  }
  
  function Background(props: Layout & Children & {
      Color: Color3
  })
      return create "Frame" {
          BackgroundColor3 = props.Color,
          props.Layout,
          props.Children
      }
  end
  

action()

Creates a callback 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 given callback 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. Higher priority numbers are ran after lower priority numbers.

• Example

  An action to listen to changed properties:

  local function changed(property: string, callback: (new) -> ())
      return action(function(instance)
          local con - instance:GetPropertyChangedSignal(property):Connect(function()
              callback(instance[property])
          end)
  
          -- disconnect on reactive scope destruction to allow gc of instance
          cleanup(function()
              con: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, callback: (...unknown) -> ()): Action
  

• Details

  Will run the given callback any time the property is changed, as well as when the action is initially run.

  The changed connection is disconnected when the reactive scope the action is ran in is destroyed.

  Runs with an action priority of 1.