Element Creators

Warning: API Documentation is still a work in progress, and Pract’s feature set has not yet been finalized.

Pract.create

Pract.create(
    classNameOrComponent: string | Pract.Component,
    props: Pract.PropsArgument?,
    children: Pract.ChildrenArgument?
): Pract.Element

Creates an element representing a newly-created instance or component. Elements are like blueprints, which Pract uses to determine how to create/destroy/modify instances to match this blueprint.

If the first argument to Pract.create is a string, Pract will call Instance.new(...) when mounted, and parent the newly-created instance to its host instance, if one exists. Pract will assign the created instance’s properties depending on the props argument provided. Pract will also rename this instance to its host child name, if provided, or the string “PractTree” by default.

The children argument is shorthand for Pract.Children and will override that symbol in props, if provided. The children table should be a record with the child names as keys, and child elements as values. The keys will determine the host child names of the child elements when mounted.

If the first argument to Pract.create is a Component (a function, typed (Pract.PropsArgument) -> Pract.Element), Pract will call this component when mounted or updating with the props provided as the component’s first argument, and then mount or update the component’s returned elements to the same host context.

Pract.stamp

Pract.stamp(
    template: Instance,
    props: Pract.PropsArgument?,
    children: Pract.ChildArgument?
): Pract.Element

Creates an element representing an instance to be cloned and decorated from the template.

When mounted, pract will call template:Clone(), parent it to the host instance, rename the template to the host child name, if provided (otherwise, it will be named “PractTree”), and assign the instance’s properties based on the props argument provided. Will mount any children provided.

Pract.decorate

Pract.decorate(
    props: Pract.PropsArgument?,
    children: Pract.ChildArgument?
): Pract.Element

Creates an element representing an existing instance to be decorated when found.

When mounted, pract will wait for a child of the host instance (if it does not exist, will throw an error) named after the host child name (if it does not exist, will instead decorate the host instance itself), and assign the instance’s properties based on the props argument provided. Will mount any children provided once the decorated instance is found.

Pract.index

Pract.index(
    children: Pract.ChildArgument?
): Pract.Element

Creates an element representing an existing instance to be indexed in a tree, but not modified.

When mounted, pract will wait for a child of the host instance (if it does not exist, will throw an error) named after the host child name (if it does not exist, will instead decorate the host instance itself. Will mount any children provided once the indexed instance is found.

Pract.portal

Pract.portal(
    hostInstance: Instance,
    children: Pract.ChildArgument?
): Pract.Element

Creates an element representing an explicit change in host context

When mounted, pract will mount its child elements with the provided hostInstance as the child elements’ host instance, and the keys of the children map as the host child names

Pract.combine

Pract.combine(
    ...: Pract.Element
): Pract.Element

Warning: The order of elements in a Pract.combine tuple matters! See the Combining Elements for more information!

See: Combining Elements for more detailed examples using Pract.combine

Returns an element which instructs pract to mount multiple elements with the same host context. A good use case for this is having components dedicated to user input mounted together with components, which decorate the same instance. With Pract.combine, user input components can be re-used, while visual components can be more specialized.

Pract.createTyped

See: Type Safety for more details on using Pract’s optional type features.

Pract.createTyped<PropsType>(
    component: ComponentTyped<PropsType>,
    props: PropsType
) -> (Types.Element)

Creates a create element representing a Component. Will respect the Props typing for that component, if defined via a ComponentTyped<PropsType> type annotation. e.g.

export type Props = {
    glowColor: Color3
}
local MyComponent: Pract.ComponentTyped<Props> = function(props)
    return Pract.stamp(path.to.my.template, {
        ImageColor3 = props.glowColor
    }
end

-- . . .

local myElement = Pract.createTyped(MyComponent, { -- This props table is properly typechecked by luau!
    glowColor = Color3.fromRGB(255, 0, 0),
})