Home > @unseenco/backstage-core > ISheet > object

ISheet.object() method

Creates a child object for the sheet

**Docs: https://backstage.unseen.co/docs/guide/manual/objects\*\*

Signature:

object<Props extends UnknownShorthandCompoundProps>(key: string, props: Props, options?: ISheetObjectOptions): ISheetObject<Props>;

Parameters

Parameter	Type	Description
key	string	Each object is identified by a key, which is a non-empty string
props	Props	The props of the object. See examples
options	ISheetObjectOptions	(Optional) Provide {reconfigure: true} to reconfigure an existing object, {visible: false} to hide it from the Studio outline panel, or {actions: { ... }} to add custom buttons to the UI. Read the example below for details.

Returns:

ISheetObject<Props>

An Object

Example

Usage:

// Create an object named "a unique key" with no props
const obj = sheet.object("a unique key", {})
obj.address.objectKey // "a unique key"


// Create an object with {x: 0}
const obj = sheet.object("obj", {x: 0})
obj.value.x // returns 0 or the current number that the user has set

// Create an object with nested props
const obj = sheet.object("obj", {position: {x: 0, y: 0}})
obj.value.position // {x: 0, y: 0}

// you can also reconfigure an existing object:
const obj = sheet.object("obj", {foo: 0})
console.log(object.value.foo) // prints 0

const obj2 = sheet.object("obj", {bar: 0}, {reconfigure: true})
console.log(object.value.foo) // prints undefined, since we've removed this prop via reconfiguring the object
console.log(object.value.bar) // prints 0, since we've introduced this prop by reconfiguring the object

assert(obj === obj2) // passes, because reconfiguring the object returns the same object

// you can add custom actions to an object:
const obj = sheet.object("obj", {foo: 0}, {
  actions: {
    // This will display a button in the UI that will reset the value of `foo` to 0
    Reset: () => {
      studio.transaction((api) => {
        api.set(obj.props.foo, 0)
      })
    }
  }
})

// you can mark props as transient (excluded from exported state JSON):
const obj = sheet.object("Camera", {
  fov: 50,
  orbitEnabled: false,
}, {
  transient: ['orbitEnabled']
})

// static props are saved to state but cannot be sequenced:
const obj = sheet.object("Camera", { fov: 50, zoom: 1 }, {
  static: ['zoom']
})