pyscript/docs/reference/API/element.md

Element

The Element API is a helpful way to create and manipulate elements in the DOM. It is a wrapper around the native DOM API, and is designed to be as intuitive as possible.

Methods and Properties

Property	Description
element	Returns the element with the given ID.
id	Returns the element's ID.
value	Returns the element's value.
innerHtml	Returns the element's inner HTML.

Method	Description
write	Writes value to element and handles various mime types. append defaults to False, if set to true, it will create a child element.
clear	Clears the element's value or content.
select	Select element from query which uses Document.querySelector().
clone	Clones the with new_id if provided and to element if provided.
remove_class	Removes one or more class name from the element.
add_class	Adds one or more class name to the element.

Element.element

Parameter	Default	Type

The element property returns the DOM element with the given ID.

    from pyscript import Element

    my_div = Element('my-div')
    print(my_div.element)

Element.id

Parameter	Default	Type

Return the element's ID.

<div id="my-div"></div>

<py-script>
    from pyscript import Element

    my_div = Element('my-div')
    print(my_div.id) # prints 'my-div'
</py-script>

Element.value

Parameter	Default	Type

Return the element's value.

<input id="my-input" value="hello world"></input>

<py-script>
    from pyscript import Element

    my_input = Element('my-input')
    print(my_input.value) # prints 'hello world'
</py-script>

Element.innerHtml

Parameter	Default	Type

Return the element's inner HTML.

<div id="my-innerHtml">
    <b>hello world</b>
</div>

<py-script>
    from pyscript import Element

    my_innerHtml = Element('my-innerHtml')
    print(my_innerHtml.innerHtml) # prints <b> hello world </b>
</py-script>

Element.write

Parameter	Default	Type
value		str or __mime_type__
append	False	bool

Writes value to element and handles various mime types. This method also contains a append parameter, which defaults to False.

Currently, these are the MIME types that are supported when rendering content using this method

Method	Inferred MIME type
__repr__	text/plain
_repr_html_	text/html
_repr_svg_	image/svg+xml
_repr_png_	image/png*
_repr_pdf_	application/pdf
_repr_jpeg_	image/jpeg*
_repr_json_	application/json
_repr_javascript_	application/javascript*
savefig	image/png

<div id="foo"></div>

<py-script>
    from pyscript import Element
    el = Element("foo")
    el.write("Hello!")
    el.write("World!") # will replace the previous content
</py-script>

If we set append to True, it will create a child element using a div.

<div id="foo"></div>

<py-script>
    from pyscript import Element
    el = Element("foo")
    el.write("Hello!", append=True)

    # This will create a child div with the id "foo-1"
    el.write("World!", append=True)
</py-script>

Element.clear

Parameter	Default	Type

Clears the element's value or content. For example, we can clear the value of an input element.

<input id="foo" value="Hello!"></input>

<py-script>
    from pyscript import Element
    el = Element("foo")
    el.clear() # Removes value from input
</py-script>

Or we can clear the content of a div element.

<div id="foo">Hello!</div>

<py-script>
    from pyscript import Element
    el = Element("foo")
    el.clear() # Removes Hello from div content
</py-script>

Element.select

Select element from query, it will look into the main Element if from_content is True. This method is a wrapper of Document.querySelector().

<div id="foo">
    <div id="bar"></div>
</div>

<py-script>
    from pyscript import Element
    el = Element("foo")
    bar = el.select("#bar")
    print(bar.id) # prints 'bar'
</py-script>

Element.clone

Parameter	Default	Type
new_id	None	str
to	None	Element

Clones the element to a new element. You can provide new_id to set a different id to the cloned element. You can also use a to element to append the cloned element to.

<div id="foo">
    HI!
</div>

<py-script>
    from pyscript import Element

    el = Element("foo")
    # Creates two divs with the id "foo" and content "HI!"
    el.clone()
</py-script>

It's always a good idea to pass a new id to the element you are cloning to avoid confusion if you need to reference the element by id again.

<div id="foo">Hello!</div>

<py-script>
    from pyscript import Element
    el = Element("foo")
    # Clones foo and its contents, but uses the id 'bar'
    el.clone(new_id="bar")
</py-script>

You can also clone an element into another element.

<div id="bond">
    Bond
</div>
<div id="james">
    James
</div>
<py-script>
    from pyscript import Element

    bond_div = Element("bond")
    james_div = Element("james")

    bond_div.clone(new_id="bond-2", to=james_div)
</py-script>

Element.remove_class

Parameter	Default	Type
classname	None	str or List[str]

Removes one or more class names from the element.

<div id="foo" class="bar baz"></div>
<py-script>
    from pyscript import Element

    el = Element("foo")
    el.remove_class("bar")
</py-script>

You can also remove multiple classes by passing a list of strings.

<div id="foo" class="bar baz"></div>
<py-script>
    from pyscript import Element

    el = Element("foo")
    el.remove_class(["bar", "baz"]) # Remove all classes from element
</py-script>

Element.add_class

Parameter	Default	Type
classname	None	str or List[str]

Adds one or more class names to the element.

<style> .red { color: red; } </style>
<div id="foo">Hi!</div>
<py-script>
    from pyscript import Element
    el = Element("foo")
    el.add_class("red")
</py-script>

You can also add multiple classes at once by passing a list of strings.

<style> .red { color: red; } .bold { font-weight: bold; } </style>
<div id="foo">Hi!</div>
<py-script>
    from pyscript import Element
    el = Element("foo")
    el.add_class(["red", "bold"])
</py-script>